Expand description
Load, animate, and render Warcraft III MDX and MDL models in Bevy.
§Load a model
Register Wc3BevyPlugin alongside Bevy’s default plugins, then attach
Wc3ModelInstance to each desired root. Instances are populated after their
assets load. Geometry and bind poses are shared; animation and materials are
private to each instance.
use bevy::prelude::*;
use bevy_wc3::{Wc3BevyPlugin, Wc3ModelInstance};
fn spawn_model(mut commands: Commands, assets: Res<AssetServer>) {
commands.spawn((
Wc3ModelInstance::new(assets.load("units/footman.mdx")),
Transform::default(),
));
}
App::new()
.add_plugins((DefaultPlugins, Wc3BevyPlugin))
.add_systems(Startup, spawn_model);Supply a Bevy camera and scene lighting to render the model. Bitmap paths
resolve beside the model first, then from the asset root, trying the literal
filename and then BLP, DDS, PNG, and TGA extensions at each location. BLP decoding is
included. Wc3TextureBindings supplies replaceable images and slot overrides.
§Work with an instance
Query Wc3Animation on the root to select sequences, blend poses, pause,
change speed, or seek. Wc3Attachments exposes attachment mounts;
Wc3ModelOwner ties detached child lifetimes to their owner. Model particles,
quad particles, and ribbons follow instance playback and ownership.
Wc3Lod selects authored geometry levels. Wc3LodSettings provides global
quality presets and automatic selection controls; Wc3LodOverride supplies
instance overrides and Wc3LodState exposes the selected level.
Wc3LightSettings configures imported scene lights. Wc3ModelCameras
exposes authored views, and Wc3CameraBinding plays them on an existing
camera. Read Wc3ModelEvent messages to interpret model event names in your
application. Use Wc3Systems to order application systems around these stages.
§Custom sources
Decode bytes with Wc3Model::decode, prepare shared assets with
prepare_model or prepare_model_with_resources, and spawn instances with
spawn_prepared_model or spawn_prepared_model_with_bindings. Resolvers
supply image and child-model handles without requiring file-backed sources.
§Rendering semantics
Meshes integrate with Bevy PBR and WC3 layer blend/depth states. Reforged
DefaultUnit texture roles, geoset tint/alpha, UV animation, and node flags are
evaluated by the renderer. Game-specific texture selection belongs to the
application. Lighting and pass ordering use Bevy semantics; exact Warcraft III
appearance is unverified. The repository’s docs/ guides explain the renderer
and feature-specific limits.
Structs§
- BlpImage
Loader - Bevy loader for
.blpimages, registered bycrate::Wc3BevyPlugin. - Model
Error - A model decoding, strict conversion, or geometry preparation failure.
- Prepared
Model - Reusable Bevy assets for one model and one set of resolved textures. Keep this value alive while spawning instances. Reprepare after changing the source model or its texture resolution.
- Wc3Animation
- Per-instance sequence playback and local-pose transitions.
Query this component on a spawned model root. Call
Self::playwhen the desired sequence changes; calling it again restarts that sequence. SetSelf::playingto pause andSelf::speedto control clock advancement. Only local node transforms blend; other properties sample the destination. - Wc3Attachment
Point - One attachment point in a model instance.
nodeis the animated MDX node;mountfollows it and gates only attached content with the visibility track. - Wc3Attachments
- Attachment points on an instance root, in source record order. IDs and names are independent of both the record index and MDX node object ID.
- Wc3Bevy
Plugin - Registers model/BLP loaders, WC3 materials, animation, and effect rendering.
- Wc3Camera
Binding - Drives an existing perspective
Camera3dfrom an authored model camera. - Wc3Camera
Sample - An evaluated authored view. Coordinates are model-local; angles are radians.
- Wc3Default
Node Camera - Marks the default active 3D camera for WC3 node flags. Without a marker, the sole active window camera (or sole active 3D camera) is selected. Multiple matching cameras require an explicit selection.
- Wc3Layer
State - WC3 shader bindings and blend/depth state extending a Bevy standard material.
- Wc3Light
- An imported light, parented to its animated WC3 node.
- Wc3Light
Settings - Conversion controls on a model’s animation root. Absence uses the defaults. These are integration scales, not calibrated Warcraft-to-physical conversions.
- Wc3Lod
Override - Complete quality configuration override on one model root.
An explicit
Wc3Lodcomponent takes precedence over its default policy. - Wc3Lod
Settings - Global LOD configuration. Use
Wc3LodOverridefor a complete local override. Larger authored level numbers mean less detail. Invalid configurations fall back to the built-in defaults; callSelf::validatewhen accepting user input. - Wc3Lod
State - Runtime geometry selection, inserted once a model is prepared and spawned.
- Wc3Model
- A version-independent source model. Conversion is strict: unsupported data is reported rather than silently discarded.
- Wc3Model
Asset - An MDX or MDL file with its resolved image and child model dependencies.
- Wc3Model
Cameras - Authored cameras on a spawned model’s animation root, in source order. This component does not create or activate Bevy cameras.
- Wc3Model
Event - An authored event key crossed during forward model playback.
- Wc3Model
Instance - Attach to an entity to spawn an MDX or MDL asset beneath it when loading finishes. The entity remains the transform and animation root.
- Wc3Model
Loader - Bevy loader for
.mdxand.mdlmodel assets and their dependencies. - Wc3Model
Owner - Lifetime owner of a child model root. Unlike
ChildOf, this relationship does not inherit transforms or visibility. Use both relationships for a following attachment; use ownership alone for particles moving in world space. Despawning the owner recursively despawns its owned models and their contents. - Wc3Model
Resources - Resolved child models in source record order. Empty or unresolved paths keep
their slots. PREM image resources (
EmitterUsesTga) are not model resources. - Wc3Node
Camera - Selects the camera driving camera-dependent node flags on a model root. Attached models inherit the nearest ancestor selection unless overridden.
- Wc3Node
Entities - Entities for a model instance’s animated nodes, keyed by authored object ID.
- Wc3Owned
Models - Child model roots owned by this entity, maintained by
Wc3ModelOwner. - Wc3Texture
Bindings - Per-instance texture choices. Attach this to a model root before spawning, or mutate it later to change the images used by that instance.
Enums§
- Wc3Lod
- Geometry quality policy for one model root. Without this component, the
effective
Wc3LodSettings::default_lodis used. - Wc3Systems
- Integration points for WC3 instance loading, animation, and effects.
- Wc3Texture
Slot - A texture use in the source model. Indices follow the MDX bitmap and PRE2 lists.
Functions§
- prepare_
model - Build shareable meshes and bind poses once. Each instance receives private layer materials so its texture bindings can change independently.
- prepare_
model_ with_ resources - Prepare shared geometry, material templates, and dependencies through consumer-defined image and child-model resolvers. This does not spawn entities.
- spawn_
model - Spawn an independently animated instance. The resolver supplies literal bitmap paths; replaceable IDs can be bound on the returned root entity.
- spawn_
prepared_ model - Spawn an independently animated instance from prepared assets.
- spawn_
prepared_ model_ with_ bindings - Spawn a prepared model with consumer-defined texture choices.
Type Aliases§
- Wc3Layer
Material - A Bevy PBR material with WC3 layer render state.