Skip to main content

bevy_wc3/
lib.rs

1//! Load, animate, and render Warcraft III MDX and MDL models in Bevy.
2//!
3//! # Load a model
4//!
5//! Register [`Wc3BevyPlugin`] alongside Bevy's default plugins, then attach
6//! [`Wc3ModelInstance`] to each desired root. Instances are populated after their
7//! assets load. Geometry and bind poses are shared; animation and materials are
8//! private to each instance.
9//!
10//! ```no_run
11//! use bevy::prelude::*;
12//! use bevy_wc3::{Wc3BevyPlugin, Wc3ModelInstance};
13//!
14//! fn spawn_model(mut commands: Commands, assets: Res<AssetServer>) {
15//!     commands.spawn((
16//!         Wc3ModelInstance::new(assets.load("units/footman.mdx")),
17//!         Transform::default(),
18//!     ));
19//! }
20//!
21//! App::new()
22//!     .add_plugins((DefaultPlugins, Wc3BevyPlugin))
23//!     .add_systems(Startup, spawn_model);
24//! ```
25//!
26//! Supply a Bevy camera and scene lighting to render the model. Bitmap paths
27//! resolve beside the model first, then from the asset root, trying the literal
28//! filename and then BLP, DDS, PNG, and TGA extensions at each location. BLP decoding is
29//! included. [`Wc3TextureBindings`] supplies replaceable images and slot overrides.
30//!
31//! # Work with an instance
32//!
33//! Query [`Wc3Animation`] on the root to select sequences, blend poses, pause,
34//! change speed, or seek. [`Wc3Attachments`] exposes attachment mounts;
35//! [`Wc3ModelOwner`] ties detached child lifetimes to their owner. Model particles,
36//! quad particles, and ribbons follow instance playback and ownership.
37//!
38//! [`Wc3Lod`] selects authored geometry levels. [`Wc3LodSettings`] provides global
39//! quality presets and automatic selection controls; [`Wc3LodOverride`] supplies
40//! instance overrides and [`Wc3LodState`] exposes the selected level.
41//!
42//! [`Wc3LightSettings`] configures imported scene lights. [`Wc3ModelCameras`]
43//! exposes authored views, and [`Wc3CameraBinding`] plays them on an existing
44//! camera. Read [`Wc3ModelEvent`] messages to interpret model event names in your
45//! application. Use [`Wc3Systems`] to order application systems around these stages.
46//!
47//! # Custom sources
48//!
49//! Decode bytes with [`Wc3Model::decode`], prepare shared assets with
50//! [`prepare_model`] or [`prepare_model_with_resources`], and spawn instances with
51//! [`spawn_prepared_model`] or [`spawn_prepared_model_with_bindings`]. Resolvers
52//! supply image and child-model handles without requiring file-backed sources.
53//!
54//! # Rendering semantics
55//!
56//! Meshes integrate with Bevy PBR and WC3 layer blend/depth states. Reforged
57//! DefaultUnit texture roles, geoset tint/alpha, UV animation, and node flags are
58//! evaluated by the renderer. Game-specific texture selection belongs to the
59//! application. Lighting and pass ordering use Bevy semantics; exact Warcraft III
60//! appearance is unverified. The repository's `docs/` guides explain the renderer
61//! and feature-specific limits.
62
63#![deny(missing_docs)]
64
65mod animation;
66mod assets;
67mod attachment;
68mod camera;
69mod effects;
70mod event;
71mod instance;
72mod light;
73mod lod;
74mod materials;
75mod plugin;
76mod preparation;
77mod schedule;
78
79pub use animation::pose::{Wc3DefaultNodeCamera, Wc3NodeCamera};
80pub use animation::Wc3Animation;
81pub use assets::{
82    BlpImageLoader, ModelError, Wc3Model, Wc3ModelAsset, Wc3ModelLoader, Wc3ModelResources,
83};
84pub use attachment::{Wc3AttachmentPoint, Wc3Attachments};
85pub use camera::{Wc3CameraBinding, Wc3CameraSample, Wc3ModelCameras};
86pub use event::Wc3ModelEvent;
87pub use instance::spawn::{
88    spawn_model, spawn_prepared_model, spawn_prepared_model_with_bindings, Wc3NodeEntities,
89};
90pub use instance::{Wc3ModelInstance, Wc3ModelOwner, Wc3OwnedModels};
91pub use light::{Wc3Light, Wc3LightSettings};
92pub use lod::{Wc3Lod, Wc3LodOverride, Wc3LodSettings, Wc3LodState};
93pub use materials::textures::{Wc3TextureBindings, Wc3TextureSlot};
94pub use materials::{Wc3LayerMaterial, Wc3LayerState};
95pub use plugin::Wc3BevyPlugin;
96pub use preparation::{prepare_model, prepare_model_with_resources, PreparedModel};
97pub use schedule::Wc3Systems;