OBJ Entity Animator

OBJ Entity Animator provides an in-game animation, modeling and behavior framework for OBJ content.

Core features include:

• Loading Wavefront OBJ + MTL files from config/objanim/import/...
• Replacing entities, blocks and items with custom 3D models
• In-game timeline-based keyframe animation
• Per-part position, rotation and scale editing
• Activity-based animations such as idle, walk, attack, sleep, eat and drink
• Behavior configuration
• Animated OBJ world blocks
• In-game model import and export
• UV editing
• Texture painting
• Mesh editing
• Custom sound support
• Model thumbnail generation
• Animation JSON export
• APIs for integration with other mods

The workflow is designed so that much of the model setup, animation and editing can happen directly inside Minecraft.

Smooth Terrain Integration

OBJAnim includes the Realistic Surface Net / Smooth Terrain system.

This system is intended to create smoother and more natural terrain surfaces instead of relying only on the traditional cubic appearance.

Version 2.0.0+ Behavior

Older versions exposed terrain modes through the M hotkey.

With the newer 2.0.0+ collision system, the old mode toggle is no longer available in the same way.

Current concept: smoother terrain rendering together with a newer collision implementation.

The terrain system and OBJ animation framework can be seen together in the main showcase video at the top of this page.

Installation

1. Install the supported NeoForge version for Minecraft 1.21.x.
2. Place the OBJAnim .jar file into your Minecraft mods/ folder.
3. Launch the game once.
4. OBJAnim creates its configuration and import folders.
5. Add your OBJ/MTL files to the appropriate import category.
6. Reload the models in-game when needed.

Import Folders

The mod uses folders under:

config/objanim/

Typical structure:

• import/entity — models for entities and mobs
• import/block — block models
• import/item — item and handheld models
• import/custommodels — miscellaneous models, props, tools and Steve-style rigs
• export — exported OBJ files and textures
• customsound — custom .ogg files
• UIelements — generated GUI/model thumbnails

Additional JSON configuration files can control behavior, video/render settings, debugging and unified configuration.

OBJAnim scans the import directories and builds an internal model index.

Open the Entity Editor

Default keybind: O

Inside the editor you can:

• Select an entity
• Load a model manually
• Create activities
• Build animations on a timeline
• Add keyframes to individual parts
• Change rotation
• Change position
• Change scale
• Preview animations
• Save animation data
• Assign custom sounds

Example Activities

• Idle
• Walk
• Attack
• Sleep
• Eat
• Drink
• Custom activities

Behavior Configuration

The BehaviorConfig system can configure behaviors such as:

• Nightly sleeping
• Lying/sleep poses
• Eating
• Drinking
• Aggression
• Attack behavior
• Idle emotions
• Following
• Wandering

Vanilla behavior preservation can be configured with:

preserveVanillaBehaviors = true

This allows OBJAnim behavior systems to coexist with supported vanilla AI behavior instead of simply removing it.

OBJAnim includes an Animated OBJ Block for placing animated 3D models directly into the world.

Registered objects include:

• Block: animated_obj_block
• BlockEntity: animated_obj_block
• Item: animated_obj_block

Possible Uses

• Decorations
• Animated signs
• Displays
• Machines
• Moving parts
• Animated statues
• Props
• Custom world objects

Get the Block

/give @p objanim:animated_obj_block

Basic Workflow

1. Place the block.
2. Open the block editor.
3. Select an OBJ model.
4. Select/configure animations.
5. Configure orientation.
6. Configure scale and other settings.
7. Tune performance if required.

Video/render-related options can be stored in:

config/objanim/video/objanim_video.json

OBJAnim includes a Model Workbench accessed through the model_editor item.

Get the Editor

/give @p objanim:model_editor

The workbench can provide tools for:

• OBJ import
• OBJ export
• Mesh editing
• Vertex editing
• Transform gizmos
• UV editing
• Texture painting
• Creating PNG textures
• Editing model geometry
• Exporting finished results

Example Steve models are included under:

assets/objanim/models/steve

Typical Workflow

1. Open the Model Workbench.
2. Import a model from the OBJAnim import folders.
3. Edit geometry or transforms.
4. Adjust UV coordinates.
5. Paint or create textures.
6. Export the result to the export folder.

GUI Thumbnails

OBJAnim can generate model thumbnails for use inside its user interfaces.

Thumbnails are stored in:

UIelements/

Possible options include:

• Automatically generated model previews
• Optional inventory icon overrides
• Per-category settings for items, blocks and entities

Texture Overrides

Imported models can use their own textures and category-specific texture configuration.

Custom Sounds

Place .ogg sound files inside:

config/objanim/customsound

Inside the animator you can:

1. Open the custom sound selection screen.
2. Preview available sounds.
3. Select a sound.
4. Assign it to an animation or activity.

This allows animated creatures, machines and props to have their own synchronized audio.

OBJAnim can map imported models to supported entities, blocks and items.

Reload Imported Models

/objanim reload

Reloads imported model content.

Apply a Specific Model

/objanim apply <modelName>

Applies a selected model to matching targets.

Apply Imported Models in Bulk

/objanim apply-all

Applies all supported imported model mappings.

These commands are useful while developing models because you can update imported files and reload them without rebuilding the entire mod.

Add Your Own Models

Place model files into the correct category:

• Entities → import/entity
• Blocks → import/block
• Items → import/item
• Miscellaneous models → import/custommodels

Then reload:

/objanim reload

Animate an Entity

1. Press O.
2. Select an entity or model.
3. Create an activity.
4. Open the part animator.
5. Select model parts.
6. Add keyframes.
7. Adjust rotation, position and scale.
8. Save.
9. Preview the animation.
10. Configure behavior if needed.
11. Assign sounds if desired.

Use the Animated OBJ Block

/give @p objanim:animated_obj_block

Then:

1. Place the block.
2. Open its editor.
3. Select an OBJ model.
4. Select animations.
5. Adjust orientation and scale.
6. Save the configuration.

Use the Model Workbench

/give @p objanim:model_editor

Use the editor to import, modify and export OBJ content, textures, UVs and meshes.

Add Custom Sounds

1. Add .ogg files to customsound/.
2. Open the animator.
3. Select a sound.
4. Preview it.
5. Assign it to an activity or keyframe.

OBJAnim can also be used as a framework by other mods.

Example Dependency

Example mods.toml configuration:

[[dependencies.yourmod]]
modId="objanim"
type="required"
versionRange="[0.2.0,)"
ordering="NONE"
side="CLIENT"

For an optional integration, use:

type="optional"

ModModelAPI

Load a model:

OBJModel model = ModModelAPI.loadModel("entity/sheep_custom");

List entity models:

var lists = ModModelAPI.listModels(ModModelRegistry.ModelCategory.ENTITY);

Search models:

var dragons = ModModelAPI.findModels("dragon");

Preload a model:

ModModelAPI.preloadModel("entity/sheep_custom");

Possible uses include:

• Custom renderers
• Automatic model loading
• Large model repositories
• Preloading frequently used content

ModModelRegistry

ModModelRegistry registry = ModModelRegistry.getInstance();
registry.initialize();

var meta = registry.getModelMetadata("entity/sheep_custom");
OBJModel model = registry.getModel("entity/sheep_custom");

The registry can be used for lower-level model metadata and cache handling.

OBJEntityManager

OBJEntityData data = OBJEntityManager.getOrCreate(entity);
OBJModel current = data.getCurrentModel();
String activity = data.getCurrentActivity();
int tick = data.getAnimationTick();

Possible uses:

• Reading current animation state
• Triggering particles
• Context-based effects
• Reacting to entity activities

ItemDisplayAPI

String path = ItemDisplayAPI.getObjModelPath(stack);

if (path != null) {
    OBJModel model = ModModelAPI.loadModel(path);
}

Possible uses:

• Custom item renderers
• Consistent OBJ model loading
• Integrating imported item models with another renderer

Development Commands

/objanim reload
/objanim apply <model>
/objanim apply-all

These commands are useful for artists and developers iterating on imported content.

Best Practices

• Use optional dependency loading when OBJAnim is not mandatory.
• Follow the OBJAnim import folder structure.
• Load models on the appropriate client-side thread where required.
• Preload large model collections when that improves runtime behavior.
• Keep model and texture sizes appropriate for the target hardware.
• Test complex animated scenes before deploying them to larger multiplayer environments.

Current Project Target

• Minecraft: 1.21.x
• Primary published version: Minecraft 1.21.1
• Loader: NeoForge
• Environment: Client & Server supported
• Editors / GUIs: Client-side interfaces

First Launch

After installation, launch Minecraft once so OBJAnim can create its configuration and import folders.

Multiplayer

The mod can be used in multiplayer environments where the required mod setup is installed appropriately.

Editor and GUI functionality is primarily operated on the client.