Skip to main content

Crate bevy_wc3

Crate bevy_wc3 

Source
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§

BlpImageLoader
Bevy loader for .blp images, registered by crate::Wc3BevyPlugin.
ModelError
A model decoding, strict conversion, or geometry preparation failure.
PreparedModel
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::play when the desired sequence changes; calling it again restarts that sequence. Set Self::playing to pause and Self::speed to control clock advancement. Only local node transforms blend; other properties sample the destination.
Wc3AttachmentPoint
One attachment point in a model instance. node is the animated MDX node; mount follows 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.
Wc3BevyPlugin
Registers model/BLP loaders, WC3 materials, animation, and effect rendering.
Wc3CameraBinding
Drives an existing perspective Camera3d from an authored model camera.
Wc3CameraSample
An evaluated authored view. Coordinates are model-local; angles are radians.
Wc3DefaultNodeCamera
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.
Wc3LayerState
WC3 shader bindings and blend/depth state extending a Bevy standard material.
Wc3Light
An imported light, parented to its animated WC3 node.
Wc3LightSettings
Conversion controls on a model’s animation root. Absence uses the defaults. These are integration scales, not calibrated Warcraft-to-physical conversions.
Wc3LodOverride
Complete quality configuration override on one model root. An explicit Wc3Lod component takes precedence over its default policy.
Wc3LodSettings
Global LOD configuration. Use Wc3LodOverride for a complete local override. Larger authored level numbers mean less detail. Invalid configurations fall back to the built-in defaults; call Self::validate when accepting user input.
Wc3LodState
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.
Wc3ModelAsset
An MDX or MDL file with its resolved image and child model dependencies.
Wc3ModelCameras
Authored cameras on a spawned model’s animation root, in source order. This component does not create or activate Bevy cameras.
Wc3ModelEvent
An authored event key crossed during forward model playback.
Wc3ModelInstance
Attach to an entity to spawn an MDX or MDL asset beneath it when loading finishes. The entity remains the transform and animation root.
Wc3ModelLoader
Bevy loader for .mdx and .mdl model assets and their dependencies.
Wc3ModelOwner
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.
Wc3ModelResources
Resolved child models in source record order. Empty or unresolved paths keep their slots. PREM image resources (EmitterUsesTga) are not model resources.
Wc3NodeCamera
Selects the camera driving camera-dependent node flags on a model root. Attached models inherit the nearest ancestor selection unless overridden.
Wc3NodeEntities
Entities for a model instance’s animated nodes, keyed by authored object ID.
Wc3OwnedModels
Child model roots owned by this entity, maintained by Wc3ModelOwner.
Wc3TextureBindings
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_lod is used.
Wc3Systems
Integration points for WC3 instance loading, animation, and effects.
Wc3TextureSlot
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§

Wc3LayerMaterial
A Bevy PBR material with WC3 layer render state.