Overview#
CraftStudio API is an essential library mod designed for developers and modders who wish to move beyond the limitations of standard Minecraft box-modeling. It provides a bridge between the CraftStudio modeling software and Minecraft, allowing for the seamless import of .csjsmodel and .csjsmodelanim files.
Unlike traditional modeling tools like Techne or Tabula, CraftStudio API supports advanced features such as keyframe-based animations, complex parent-child hierarchies, and real-time synchronization between the client and server. It is a dependency mod, meaning it does not add gameplay content like mobs or items on its own, but is required for other mods that utilize its rendering engine.
Key Features#
The API introduces several technical advancements to the Minecraft rendering pipeline:
- Native Format Support: Direct import of
.csjsmodel(models) and.csjsmodelanim(animations) files. - Advanced Animations: Keyframe-based position and rotation animations that are much smoother than hard-coded Java animations.
- Synchronization: A built-in system to ensure animations are perfectly synced between the server and all connected clients.
- Versatility: Supports custom models for both Entities and Blocks (via Tile Entity Special Renderers).
- Loading Feedback: Includes a custom progress bar during the game's startup to track the loading of complex models and animations.
Model System#
The API uses a custom JSON-based format exported from CraftStudio. This system allows for more flexible block properties than the standard Minecraft engine.
Supported Model Properties
| Property | Description |
|---|---|
| Position | The X, Y, Z coordinates of the block relative to its parent. |
| Rotation | Euler angles (Yaw, Pitch, Roll) for precise orientation. |
| Size | The dimensions of the cuboid block. |
| Offset | Adjusts the visual position of the block without moving its pivot point. |
| Stretch | Allows for slight scaling adjustments of the model parts. |
Texture Mapping
Currently, the API specifically supports the "Collapsed" unwrap mode for textures. This ensures that textures are applied correctly to the complex hierarchies created in CraftStudio. Modders can use external software to paint textures once the UV map is generated.
Animation System#
The animation system is the core of the CraftStudio API, providing a fluid way to bring entities and blocks to life.
- Keyframe Interpolation: The API automatically calculates the movement between defined keyframes for smooth transitions.
- Hold Last Keyframe: A feature that allows an animation to stay in its final pose rather than snapping back to the default state.
- Reverse Animations: Animations can be played backward, which is useful for opening/closing doors or similar mechanical movements.
- Animation Handler: A centralized system (
AnimationHandler) manages which animations are playing on an entity at any given time.
| Feature | Supported | Notes |
|---|---|---|
| Position Animation | Yes | Moves parts over time. |
| Rotation Animation | Yes | Rotates parts around their pivot. |
| Size/Stretch Anim | No | Currently ignored in the animation files. |
| Server Sync | Yes | Animations triggered on server reflect on all clients. |
Entity & Block Integration#
For developers, the API simplifies the process of registering and rendering custom assets.
Entities
To create an animated entity, developers implement the IAnimatedEntity interface. This allows the entity to hold an AnimationHandler and respond to triggers like walking, attacking, or idling. The ModelCraftStudio class replaces the standard ModelBase for these entities.
Blocks (TESR)
For blocks that require complex shapes or animations (like custom machinery or decorative furniture), the API supports Tile Entity Special Renderers (TESR). By linking a Tile Entity to a CraftStudio model, blocks can have moving parts that react to player interaction or internal logic.
Commands & Utilities#
The mod includes built-in tools to assist developers during the modding process:
- UV Map Export: Developers can use the in-game command
/crafty uvmap(or similar depending on the specific sub-version) to export the UV layout of a registered model. This is essential for creating accurate textures in external image editors. - Progress Bar: During the Minecraft loading screen, the API adds a specialized progress bar. This prevents the game from appearing frozen while it parses large amounts of model and animation data.
Mechanics & Technical Specs#
The API operates by overriding the standard rendering calls. When a model is loaded, it is stored in a registry that can be accessed by any mod using the API as a dependency.
- File Locations: Models should be placed in
assets/modid/models/craftstudio/and animations inassets/modid/animations/craftstudio/. - Naming Conventions: It is highly recommended that models do not have multiple blocks with the same name, as this can cause conflicts during the animation interpolation process.
- Performance: The API is optimized to handle multiple animated entities simultaneously without significant FPS drops, thanks to its efficient handling of vertex transformations.
