Your first app
Write a NEO app from scratch: an App, the default plugins, a startup system that spawns a 3D scene and an update system that moves it.
On this page
This page builds a small NEO app step by step: it prints a message, opens a window, shows a lit cube and then spins it. Each step adds one idea. By the end you have used the App, plugins, systems, components, resources and queries, the pieces every NEO game is made of.
You need a working toolchain first; see Set up the engine.
Hello, world#
Every NEO program starts with an App. You add systems to it, plain Rust functions that the engine calls, and then run it.
use neo::prelude::*;
fn main() {
App::new().add_systems(Startup, hello_world).run();
}
fn hello_world() {
info!("Hello, World!");
}neo::prelude::* brings in the types you use most. Startup is a schedule: systems in it run once, when the app starts. This app has no plugins, so it runs its startup systems and exits.
Example: cargo run --example hello_world.
Open a window#
DefaultPlugins adds everything a game needs: a window, rendering, input, assets, audio, UI, time and more. With it, the app keeps running until you close the window.
use neo::prelude::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins.set(WindowPlugin {
primary_window: Some(Window {
title: "My first NEO app".into(),
..default()
}),
..default()
}))
.run();
}.set(...) replaces one plugin's settings inside the group. See Windows for every window setting.
Spawn a scene#
The world holds entities, and each entity is a bundle of components. A startup system spawns a cube, a light and a camera with Commands:
use neo::prelude::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, setup)
.run();
}
fn setup(
mut commands: Commands,
mut meshes: ResMut<Assets<Mesh>>,
mut materials: ResMut<Assets<StandardMaterial>>,
) {
// a round base
commands.spawn((
Mesh3d(meshes.add(Circle::new(4.0))),
MeshMaterial3d(materials.add(Color::WHITE)),
Transform::from_rotation(Quat::from_rotation_x(-std::f32::consts::FRAC_PI_2)),
));
// a cube
commands.spawn((
Mesh3d(meshes.add(Cuboid::new(1.0, 1.0, 1.0))),
MeshMaterial3d(materials.add(Color::srgb_u8(124, 144, 255))),
Transform::from_xyz(0.0, 0.5, 0.0),
));
// a light
commands.spawn((
PointLight {
shadow_maps_enabled: true,
..default()
},
Transform::from_xyz(4.0, 8.0, 4.0),
));
// a camera
commands.spawn((
Camera3d::default(),
Transform::from_xyz(-2.5, 4.5, 9.0).looking_at(Vec3::ZERO, Vec3::Y),
));
}| Piece | What it is |
|---|---|
Commands | Queues changes to the world: spawning, despawning, inserting components. They apply after the system runs. |
ResMut<Assets<Mesh>> | Mutable access to a resource, here the store of meshes. meshes.add(...) returns a Handle<Mesh>. |
Mesh3d, MeshMaterial3d | Components that give an entity a mesh and a material to draw. |
Transform | Where the entity is: translation, rotation and scale. |
Camera3d, PointLight | A 3D camera and a light. Adding a component often adds the others it needs. |
Example: cargo run --example 3d_scene.
Make it move#
Systems in Update run every frame. Mark the cube with your own component, then query for it:
#[derive(Component)]
struct Spin {
speed: f32, // radians per second
}
fn spin(time: Res<Time>, mut cubes: Query<(&mut Transform, &Spin)>) {
for (mut transform, spin) in &mut cubes {
transform.rotate_y(spin.speed * time.delta_secs());
}
}Add Spin { speed: 1.0 } to the cube's bundle in setup, and register the system:
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, setup)
.add_systems(Update, spin)
.run();Query<(&mut Transform, &Spin)>visits every entity that has both components, with write access to the transform.Res<Time>reads the time resource. Multiplying bydelta_secs()makes the speed the same at any frame rate.- The engine runs systems that don't conflict in parallel. Two systems that both write
Transformrun one after the other.
Respond to input#
Read the keyboard through the ButtonInput<KeyCode> resource:
fn reverse(keys: Res<ButtonInput<KeyCode>>, mut cubes: Query<&mut Spin>) {
if keys.just_pressed(KeyCode::Space) {
for mut spin in &mut cubes {
spin.speed = -spin.speed;
}
}
}Add it to Update next to spin: .add_systems(Update, (spin, reverse)).
Where to go from here#
| To learn | Read |
|---|---|
| How entities, components and systems fit together | ECS |
| Grouping your setup into a reusable piece | Plugins |
| Loading models, textures and sounds | Assets |
| Cameras, materials and lights | 3D rendering |
| Menus and HUDs | UI |