Gameplay kit

The gameplay kit is the set of engine crates that make a third-person game: the character, its controls, its camera and its sound, plus a plugin that assembles them into a running app. The GASP template's starter game is the kit playing a level, and every project made from the template uses it. Because the kit lives in the engine rather than in your project, your project picks up engine fixes without copying code.

This page is for creators who write Rust game code. If you build with the Studio and scripts, you already have all of this; see Samples and templates.

The crates#

The gameplay kit also brings in neo_anim_ecs, which exposes motion matching, leg IK, rigs and physical animation as ECS components, for games that want those pieces on their own entities.

A playable character in ten lines#

This is the kit's own example (examples/third_person.rs, with the content folder pointed at your game's), a complete third-person game: the template's character and animation library, a floor, controls, the orbit camera and a sun.

use bevy::prelude::*;
use neo_gameplay_kit::{AuthoredScene, GameplayKitPlugin};

fn main() {
    let assets = concat!(env!("CARGO_MANIFEST_DIR"), "/assets"); // your game's content folder
    App::new()
        .add_plugins(DefaultPlugins.set(AssetPlugin {
            file_path: assets.into(),
            ..default()
        }))
        .add_plugins(GameplayKitPlugin::default().with_scene(AuthoredScene::default()))
        .run();
}

Run it from the engine workspace with cargo run -p neo_gameplay_kit --example third_person.

Configuring the kit#

GameplayKitPlugin also has fields for the parts it adds by default: frame_clock, input, camera, lighting, audio and multiplayer. With multiplayer on (the default), remote players in a platform session become characters too; without a session it does nothing. See Multiplayer.

A standalone game's app#

A game that runs on its own builds its app with neo_gameplay_kit::app, which sets up the window, the engine's default plugins and the project's content layers (its own assets/ over the template's).

SmokeTestPlugin(SmokeConfig::parse(&args)), from neo_gameplay_kit::smoke, adds a --smoke <dir> flag: once the simulation is up, scripted input drives the player through idle, walk, run and a sprint with a jump, logs its position every second, writes <dir>/smoke.png and <dir>/smoke.txt, and exits with an error if the player moved less than a metre. Projects made from the template have it.

Building it yourself#

To use the kits without GameplayKitPlugin:

1. Depend on them in the game crate's Cargo.toml:

   TOMLCopy

   neo_character = { workspace = true }
   neo_input_kit = { workspace = true }
   neo_gameplay_camera = { workspace = true }
   neo_audio_kit = { workspace = true }   # optional

   They're enabled by default once linked; list them in the project's neo.toml to be explicit:

   TOMLCopy

   [plugins]
   neo_character = true
   neo_input_kit = true
   neo_gameplay_camera = true
   neo_audio_kit = true

   Also list them in your game plugin's descriptor dependencies so they're built before it. See Plugins and neo.toml.

2. Build a simulation from a level and an animation library, and step it with the input kit's controls:

   RustCopy

   use bevy::prelude::*;
   use neo_character::{CharacterSim, level::Level};
   use neo_gameplay_camera::{GameplayCamera, OrbitCamera};
   use neo_input_kit::{CharacterControls, InputKitSystems};
   
   #[derive(Resource)]
   struct Game { sim: CharacterSim, lib: bevy_motion_matching::library::Library }
   
   fn step(mut g: ResMut<Game>, controls: Res<CharacterControls>, time: Res<Time>) {
       let Game { sim, lib } = &mut *g;
       sim.step(lib, &controls.input, time.delta_secs());
   }
   
   fn follow(g: Res<Game>, mut cam: ResMut<OrbitCamera>, time: Res<Time>,
             mut q: Single<&mut Transform, With<GameplayCamera>>) {
       let target = g.sim.character.position + Vec3::Z * 133.0; // capsule centre + boom
       **q = cam.follow(target, time.delta_secs());
   }
   
   // app.add_systems(Update, (step.after(InputKitSystems), follow.after(step)));

   CharacterSim::new(&lib, level) takes your level (boxes with surfaces); with_physics adds a physics asset for physical animation and ragdolls; spawn_npc adds more characters.

3. Foley: sim.foley collects each frame's events (footsteps, landings, slides, hand plants, impacts). Setting KitAssets::foley_bank makes the kit play them; a game with its own sound design plays them through neo_audio_kit::foley::FoleyPlayer.

The player's model#

The player wears the game's character model unless the character kit's settings say otherwise. Set them in [plugin.neo_character] in neo.toml, in the Plugins panel, or with plugins.settings.set:

The model keeps its own materials, other characters keep the game's model, and a model that fails to load falls back to the game's. character.player_model reports the state. The player's platform avatar works the same way; see How avatars work in games.

Guarantees#

The simulation is deterministic: the same inputs give bit-identical results on every run, which is what lets a game replay or compare runs.

Next steps#

• Camera
• Plugins and neo.toml
• Multiplayer
• Samples and templates