570 lines
19 KiB
Markdown
570 lines
19 KiB
Markdown
# Scene format (`.forge.ron`)
|
|
|
|
Bevy Forge stores scenes as human-readable [RON](https://github.com/ron-rs/ron) documents with the
|
|
`.forge.ron` extension. A scene file contains **editor data only** - entities, hierarchy, transforms
|
|
and components. It never contains generated code and is not Bevy's `.scn.ron` dynamic-scene format.
|
|
BSN or imperative Rust is generated from a scene on demand; see the [BSN export guide](bsn-export.md).
|
|
|
|
This page documents format version **1** as written by the editor and understood by the core crate.
|
|
Related pages: [architecture](architecture.md), [README](../README.md).
|
|
|
|
## Files and naming
|
|
|
|
- Scenes live in `<project>/scenes/`. `Project::list_scenes()` lists the `*.forge.ron` files there.
|
|
- The editor's suggested filename is the scene display name run through `slugify`: ASCII
|
|
letters/digits are lowercased, whitespace and `-`, `_`, `.` collapse to `-`, and an empty result
|
|
becomes `scene` (for example `Level 01` -> `level-01.forge.ron`). The name inside the file is
|
|
separate and can be any UTF-8 string.
|
|
- The editor refuses to save under any other extension, and `Project::save_scene` refuses paths
|
|
outside the project root.
|
|
- Files are UTF-8 RON produced with a two-space pretty printer. Writers use `\n` line endings.
|
|
RON comments are legal in the format but the editor does not write them.
|
|
- Whitespace and line breaks are not significant. The editor's writer puts one struct field per
|
|
line and expands nested vectors/colours the same way; the examples on this page are written more
|
|
compactly for readability and parse identically.
|
|
|
|
## Complete example
|
|
|
|
A small 3D scene with two roots, a directional light and a primitive mesh:
|
|
|
|
```ron
|
|
(
|
|
format_version: 1,
|
|
name: "Garden",
|
|
entities: {
|
|
1: (
|
|
id: 1,
|
|
name: "Sun",
|
|
parent: None,
|
|
children: [],
|
|
transform: (
|
|
translation: (x: -4.0, y: 8.0, z: -6.0),
|
|
rotation: (x: 45.0, y: 30.0, z: 0.0),
|
|
scale: (x: 1.0, y: 1.0, z: 1.0),
|
|
),
|
|
components: [
|
|
(
|
|
type: directional_light,
|
|
data: (
|
|
color: (r: 1.0, g: 0.95, b: 0.85, a: 1.0),
|
|
illuminance: 10000.0,
|
|
shadows: true,
|
|
),
|
|
),
|
|
],
|
|
locked: false,
|
|
),
|
|
2: (
|
|
id: 2,
|
|
name: "Ground",
|
|
parent: None,
|
|
children: [],
|
|
transform: (
|
|
translation: (x: 0.0, y: 0.0, z: 0.0),
|
|
rotation: (x: 0.0, y: 0.0, z: 0.0),
|
|
scale: (x: 1.0, y: 1.0, z: 1.0),
|
|
),
|
|
components: [
|
|
(
|
|
type: mesh3d,
|
|
data: (
|
|
mesh: (
|
|
source: primitive,
|
|
value: cuboid(size: (x: 12.0, y: 0.2, z: 12.0)),
|
|
),
|
|
material: (
|
|
base_color: (r: 0.35, g: 0.55, b: 0.3, a: 1.0),
|
|
metallic: 0.0,
|
|
perceptual_roughness: 0.9,
|
|
unlit: false,
|
|
),
|
|
),
|
|
),
|
|
],
|
|
locked: false,
|
|
),
|
|
},
|
|
roots: [1, 2],
|
|
next_id: 3,
|
|
)
|
|
```
|
|
|
|
A 2D scene with hierarchy, a sprite, text, a camera, a hidden component and a custom component:
|
|
|
|
```ron
|
|
(
|
|
format_version: 1,
|
|
name: "Platformer",
|
|
entities: {
|
|
1: (
|
|
id: 1,
|
|
name: "Camera",
|
|
parent: None,
|
|
children: [],
|
|
transform: (
|
|
translation: (x: 0.0, y: 0.0, z: 10.0),
|
|
rotation: (x: 0.0, y: 0.0, z: 0.0),
|
|
scale: (x: 1.0, y: 1.0, z: 1.0),
|
|
),
|
|
components: [
|
|
(type: camera2d),
|
|
],
|
|
locked: false,
|
|
),
|
|
2: (
|
|
id: 2,
|
|
name: "Player",
|
|
parent: None,
|
|
children: [3],
|
|
transform: (
|
|
translation: (x: 0.0, y: 1.0, z: 0.0),
|
|
rotation: (x: 0.0, y: 0.0, z: 0.0),
|
|
scale: (x: 1.0, y: 1.0, z: 1.0),
|
|
),
|
|
components: [
|
|
(
|
|
type: sprite,
|
|
data: (
|
|
image: Some("textures/player.png"),
|
|
color: (r: 1.0, g: 1.0, b: 1.0, a: 1.0),
|
|
custom_size: Some((x: 32.0, y: 48.0)),
|
|
flip_x: false,
|
|
flip_y: false,
|
|
),
|
|
),
|
|
(type: visibility, data: visible),
|
|
(
|
|
type: custom,
|
|
data: (
|
|
type_path: "forge_demo::Orbit",
|
|
fields: [
|
|
(name: "radius", expr: "2.0"),
|
|
(name: "speed", expr: "-0.5"),
|
|
],
|
|
),
|
|
),
|
|
],
|
|
locked: false,
|
|
),
|
|
3: (
|
|
id: 3,
|
|
name: "Label",
|
|
parent: Some(2),
|
|
children: [],
|
|
transform: (
|
|
translation: (x: 0.0, y: 32.0, z: 0.0),
|
|
rotation: (x: 0.0, y: 0.0, z: 0.0),
|
|
scale: (x: 1.0, y: 1.0, z: 1.0),
|
|
),
|
|
components: [
|
|
(
|
|
type: text2d,
|
|
data: (
|
|
text: "Bevy Forge",
|
|
font_size: 24.0,
|
|
color: (r: 0.9, g: 0.9, b: 1.0, a: 1.0),
|
|
),
|
|
),
|
|
],
|
|
locked: false,
|
|
),
|
|
},
|
|
roots: [1, 2],
|
|
next_id: 4,
|
|
)
|
|
```
|
|
|
|
## Top-level fields
|
|
|
|
`SceneDoc` is a RON struct with these fields, in this order:
|
|
|
|
| Field | Type | Meaning |
|
|
|---|---|---|
|
|
| `format_version` | `u32` | Schema version. Currently `1`; see [Versioning](#versioning). |
|
|
| `name` | `String` | Scene display name, independent of the filename. May be empty (validation warns). |
|
|
| `entities` | map `u64 -> EntityNode` | All entities, keyed by ID. Map order is insertion order and is stable across saves. |
|
|
| `roots` | `[u64]` | Root entity IDs in display order. Every entity is either a root or a descendant of one. |
|
|
| `next_id` | `u64` | Next identity to allocate. Must be greater than every ID in `entities`; IDs are never reused. |
|
|
|
|
## Entity fields
|
|
|
|
| Field | Type | Meaning |
|
|
|---|---|---|
|
|
| `id` | `u64` | Must equal the key in `entities`. |
|
|
| `name` | `String` | Display name; arbitrary UTF-8. Used for hierarchy labels and generated `Name(...)`. |
|
|
| `parent` | `Option<u64>` | `None` for roots, otherwise the containing entity. |
|
|
| `children` | `[u64]` | Ordered child IDs. Order is preserved in the hierarchy and in generated code. |
|
|
| `transform` | `Transform` | Mandatory local transform; see below. |
|
|
| `components` | `[ComponentData]` | Ordered component list; at most one component per `key()`. |
|
|
| `locked` | `bool` | Editor-only. `true` blocks viewport transforms and gizmos, not hierarchy edits or deletion. Missing in old files defaults to `false`. |
|
|
|
|
## Transforms and coordinates
|
|
|
|
`Transform` mirrors Bevy's `Transform`:
|
|
|
|
```ron
|
|
transform: (
|
|
translation: (x: 1.0, y: 2.0, z: 0.5),
|
|
rotation: (x: 0.0, y: 45.0, z: 0.0),
|
|
scale: (x: 1.0, y: 1.0, z: 1.0),
|
|
)
|
|
```
|
|
|
|
- `translation` is the local position. 2D scenes use X/Y; Z is used as the draw-order axis by the
|
|
2D viewport. 3D scenes use all three axes.
|
|
- `rotation` is **XYZ Euler angles in degrees**, not radians and not a quaternion. This is the value
|
|
the inspector edits. Export converts it with
|
|
`Quat::from_euler(EulerRot::XYZ, x.to_radians(), y.to_radians(), z.to_radians())`.
|
|
- `scale` is a per-axis multiplier. A zero scale is legal in the file but produces a validation
|
|
warning.
|
|
- World transforms are computed by composing local transforms down the parent chain. Parents affect
|
|
children; moving a parent moves its subtree in the viewports. Scene files always store local
|
|
transforms, never world transforms.
|
|
- All numbers are `f32` RON floats. Non-finite values (`NaN`, `inf`) are representable in RON but
|
|
rejected by validation and code generation.
|
|
|
|
Colours use the four-field `Color` struct with channels in `0.0..=1.0`:
|
|
|
|
```ron
|
|
color: (r: 0.35, g: 0.55, b: 0.95, a: 1.0)
|
|
```
|
|
|
|
The editor edits these as sRGB colours; the generated code emits `Color::srgba(r, g, b, a)`.
|
|
|
|
## Components
|
|
|
|
`components` is an ordered list of serde-tagged values. Every entry has a `type` tag and, except for
|
|
unit variants, a `data` payload. Tags and enum payloads are **bare RON identifiers**, not strings -
|
|
write `type: sprite`, not `type: "sprite"`:
|
|
|
|
```ron
|
|
(
|
|
type: sprite,
|
|
data: (
|
|
image: Some("textures/player.png"),
|
|
color: (r: 1.0, g: 1.0, b: 1.0, a: 1.0),
|
|
custom_size: Some((x: 32.0, y: 48.0)),
|
|
flip_x: false,
|
|
flip_y: false,
|
|
),
|
|
)
|
|
```
|
|
|
|
The tag values and uniqueness keys are:
|
|
|
|
| Tag | Payload | `key()` | Notes |
|
|
|---|---|---|---|
|
|
| `sprite` | `SpriteData` | `sprite` | 2D sprite |
|
|
| `text2d` | `Text2dData` | `text2d` | world-space text |
|
|
| `camera2d` | none | `camera2d` | unit: `(type: camera2d)` |
|
|
| `camera3d` | none | `camera3d` | unit: `(type: camera3d)` |
|
|
| `point_light` | `PointLightData` | `point_light` | |
|
|
| `directional_light` | `DirectionalLightData` | `directional_light` | |
|
|
| `mesh3d` | `Mesh3dData` | `mesh3d` | primitive or asset mesh plus material |
|
|
| `visibility` | `VisibilityMode` | `visibility` | `inherited`, `visible` or `hidden` |
|
|
| `custom` | `CustomComponent` | `custom:<type_path>` | one per custom type path |
|
|
|
|
`Name` and `Transform` are **not** components in this format - they are entity fields. Adding a
|
|
component whose key already exists is refused; use the inspector's edit controls to change values.
|
|
|
|
### Sprite
|
|
|
|
```ron
|
|
(
|
|
type: sprite,
|
|
data: (
|
|
image: Some("textures/player.png"),
|
|
color: (r: 1.0, g: 1.0, b: 1.0, a: 1.0),
|
|
custom_size: Some((x: 64.0, y: 64.0)),
|
|
flip_x: false,
|
|
flip_y: false,
|
|
),
|
|
)
|
|
```
|
|
|
|
| Field | Type | Meaning |
|
|
|---|---|---|
|
|
| `image` | `Option<String>` | Path relative to `assets/`; omit `Some` for a solid-colour sprite |
|
|
| `color` | `Color` | Tint; defaults to white |
|
|
| `custom_size` | `Option<Vec2>` | Explicit size; `None` uses the texture's native size |
|
|
| `flip_x`, `flip_y` | `bool` | Mirror the texture on that axis |
|
|
|
|
A sprite with no image and no custom size renders nothing; validation reports a warning.
|
|
|
|
### Text2d
|
|
|
|
```ron
|
|
(
|
|
type: text2d,
|
|
data: (
|
|
text: "Hello\nBevy",
|
|
font_size: 32.0,
|
|
color: (r: 1.0, g: 1.0, b: 1.0, a: 1.0),
|
|
),
|
|
)
|
|
```
|
|
|
|
`font_size` is in pixels and must be greater than zero. The text string is escaped as a normal RON
|
|
string and becomes a Rust string literal on export. Empty text is allowed but produces a warning.
|
|
|
|
### Cameras
|
|
|
|
```ron
|
|
(type: camera2d)
|
|
```
|
|
|
|
```ron
|
|
(type: camera3d)
|
|
```
|
|
|
|
A scene can contain both, but the 2D and 3D camera mix produces a warning. Optional cameras are
|
|
reported as info; more than one camera is also info. Neither variant stores projection fields in
|
|
this version.
|
|
|
|
### Point light
|
|
|
|
```ron
|
|
(
|
|
type: point_light,
|
|
data: (
|
|
color: (r: 1.0, g: 0.8, b: 0.6, a: 1.0),
|
|
intensity: 800.0,
|
|
range: 20.0,
|
|
shadows: true,
|
|
),
|
|
)
|
|
```
|
|
|
|
`intensity` must be non-negative and `range` must be positive; `shadows` maps to
|
|
`shadow_maps_enabled` in generated BSN.
|
|
|
|
### Directional light
|
|
|
|
```ron
|
|
(
|
|
type: directional_light,
|
|
data: (
|
|
color: (r: 1.0, g: 0.95, b: 0.85, a: 1.0),
|
|
illuminance: 10000.0,
|
|
shadows: true,
|
|
),
|
|
)
|
|
```
|
|
|
|
`illuminance` must be non-negative. The light's direction comes from the entity's rotation.
|
|
|
|
### Mesh3d
|
|
|
|
```ron
|
|
(
|
|
type: mesh3d,
|
|
data: (
|
|
mesh: (
|
|
source: primitive,
|
|
value: cuboid(size: (x: 1.0, y: 1.0, z: 1.0)),
|
|
),
|
|
material: (
|
|
base_color: (r: 0.45, g: 0.62, b: 0.95, a: 1.0),
|
|
metallic: 0.0,
|
|
perceptual_roughness: 0.5,
|
|
unlit: false,
|
|
),
|
|
),
|
|
)
|
|
```
|
|
|
|
`MeshSource` is tagged `source` / `value`:
|
|
|
|
- `source: primitive` with one of the five `PrimitiveShape` values below.
|
|
- `source: asset` with a string mesh path, for example
|
|
`value: "models/robot.gltf#Mesh0/Primitive0"`.
|
|
|
|
Primitive shapes (RON value for `value`):
|
|
|
|
| Shape | RON |
|
|
|---|---|
|
|
| Cuboid | `cuboid(size: (x: 2.0, y: 1.0, z: 0.5))` |
|
|
| Sphere | `sphere(radius: 0.5)` |
|
|
| Plane | `plane(size: (x: 10.0, y: 10.0))` - width and depth in X/Z |
|
|
| Cylinder | `cylinder(radius: 0.5, height: 1.0)` |
|
|
| Capsule | `capsule(radius: 0.5, length: 1.0)` |
|
|
|
|
`MaterialData` fields:
|
|
|
|
| Field | Type | Meaning |
|
|
|---|---|---|
|
|
| `base_color` | `Color` | Albedo / base colour |
|
|
| `metallic` | `f32` | 0 = dielectric, 1 = metal; values outside `0..=1` warn |
|
|
| `perceptual_roughness` | `f32` | 0 = mirror, 1 = rough; values outside `0..=1` warn |
|
|
| `unlit` | `bool` | Emit an unlit material |
|
|
|
|
Asset mesh paths are validated for existence and kind when an asset index is available, and are
|
|
emitted as `Mesh3d("<path>")` in BSN. The material is always emitted inline, so no material asset
|
|
loader is required.
|
|
|
|
### Visibility
|
|
|
|
```ron
|
|
(type: visibility, data: hidden)
|
|
```
|
|
|
|
The payload is one of the bare RON identifiers `inherited`, `visible` or `hidden`. `hidden` is
|
|
equivalent to Bevy's `Visibility::Hidden`; toggling the hierarchy eye adds/removes this component.
|
|
An entity without a visibility component is treated as `inherited`.
|
|
|
|
### Custom components
|
|
|
|
```ron
|
|
(
|
|
type: custom,
|
|
data: (
|
|
type_path: "forge_demo::Orbit",
|
|
fields: [
|
|
(name: "radius", expr: "2.0"),
|
|
(name: "speed", expr: "-0.5"),
|
|
(name: "axis", expr: "Vec3::Y"),
|
|
],
|
|
),
|
|
)
|
|
```
|
|
|
|
| Field | Type | Meaning |
|
|
|---|---|---|
|
|
| `type_path` | `String` | A Rust type path such as `Health`, `my_game::Health` or `my_game::components::Health` |
|
|
| `fields` | `[CustomField]` | Ordered field initialisers |
|
|
| `fields[].name` | `String` | Rust field identifier |
|
|
| `fields[].expr` | `String` | Raw Rust/BSN expression, stored verbatim and emitted after `name:` |
|
|
|
|
Custom components are the escape hatch for project-specific types. The editor validates only the
|
|
shape of the type path and field names, and that expressions are non-empty; it does not parse Rust.
|
|
The component type must derive `Component` plus `Default + Clone` or `FromTemplate` - see
|
|
[custom-component requirements](bsn-export.md#custom-component-requirements). Two custom components
|
|
with different type paths can coexist on one entity; the same path may appear only once.
|
|
|
|
## Ids, forests and ordering
|
|
|
|
Every scene is a forest of entities:
|
|
|
|
- Each entity has exactly one parent (`None` for roots) and appears in exactly one place: either
|
|
`roots` or one parent's `children` list.
|
|
- `parent` and `children` must agree (`child.parent == Some(parent_id)`). `roots` entries must have
|
|
`parent: None`.
|
|
- Cycles are invalid and are rejected by `reparent`; a hand-edited file with a cycle fails
|
|
structural validation.
|
|
- `id` is unique and stable for the lifetime of the scene; IDs are never reused after deletion.
|
|
`next_id` must remain greater than every entity ID. Gaps are fine.
|
|
- Order matters: `roots` controls root order, each `children` list controls sibling order, and both
|
|
are preserved by duplicate/reparent and by code generation.
|
|
- Deleting an entity removes its whole subtree. Duplicating deep-copies the subtree, inserts the
|
|
copy immediately after the original among its siblings, and suffixes the root copy's name with
|
|
`" Copy"`.
|
|
- `locked` is editor metadata and has no effect on export.
|
|
|
|
`SceneDoc::check_integrity()` returns a list of structural problems (empty when valid). Validation
|
|
includes these checks.
|
|
|
|
## Versioning
|
|
|
|
`format_version` is the scene schema version, not the Bevy Forge application version. It is currently
|
|
`1` (`FORMAT_VERSION`).
|
|
|
|
- The editor writes `1`.
|
|
- On load, version `0` is normalized to `1` in memory and the data is kept (a permissive path for
|
|
early files).
|
|
- There is no migration framework yet: the loader otherwise parses the document as the current
|
|
schema. Treat version `1` as the only supported schema.
|
|
- Additive fields should be serde-defaultable so older files still load; breaking changes bump
|
|
`format_version`.
|
|
- Generated code is not stored in the file and is not versioned by this field. Export behaviour is
|
|
governed by the codegen contract and the target Bevy version (0.20).
|
|
|
|
## Asset paths
|
|
|
|
Sprite images and asset meshes use paths **relative to the project's Bevy assets directory**, with
|
|
`/` separators:
|
|
|
|
```ron
|
|
image: Some("textures/player.png")
|
|
```
|
|
|
|
```ron
|
|
value: "models/robot.gltf#Mesh0/Primitive0"
|
|
```
|
|
|
|
Rules (violations are validation errors):
|
|
|
|
- No absolute paths.
|
|
- No `..` path components.
|
|
- No backslashes.
|
|
- With an asset index, the file must exist and its kind must match the use (for example, an `.ogg`
|
|
cannot be used as a sprite image; `.png`, `.jpg`, `.jpeg`, `.webp`, `.bmp`, `.tga`, `.ktx2` and
|
|
`.dds` are images, while `.gltf`, `.glb`, `.obj` and `.fbx` are meshes).
|
|
|
|
Projects with an `assets/` directory use it directly. Projects without one treat the project root as
|
|
the assets directory. The editor resolves asset paths through the project, never the process working
|
|
directory.
|
|
|
|
## Saving and autosave
|
|
|
|
- `Project::save_scene` serializes with the pretty RON printer and writes **atomically**: it writes
|
|
a temporary `.<filename>.tmp-<pid>` file in the destination directory and renames it over the
|
|
target. A crash during save leaves the previous file intact.
|
|
- The editor refuses non-`.forge.ron` filenames and `Project::save_scene` refuses paths outside the
|
|
project root. Parent directories are created for save-as paths.
|
|
- Saving marks the session clean; the title dot and quit guard use that flag.
|
|
- When autosave is enabled (`autosave_secs > 0`, default 60 seconds), a dirty document is written to
|
|
`<project>/.forge/autosave.forge.ron` at most once per interval. Autosave is best-effort: it does
|
|
not mark the session saved and is not a substitute for saving. Set `autosave_secs` to 0 to disable
|
|
it.
|
|
- Editor preferences are stored separately in `bevy-forge/config.ron` under the platform config
|
|
directory; that file is not a scene.
|
|
|
|
## Validation
|
|
|
|
`validate_scene(doc, assets: Option<&AssetIndex>)` returns a `ValidationReport` with `Error`,
|
|
`Warning` and `Info` issues. `forge validate` prints them and uses the exit code to distinguish
|
|
"valid" from "has errors"; the editor shows per-entity issues and summary counts. Passing `None` for
|
|
the asset index disables missing-asset checks.
|
|
|
|
**Errors**
|
|
|
|
- Structural invariant failures: missing parent/child/root, cycles, mismatched node ID, duplicate
|
|
references.
|
|
- Non-finite transform, rotation or scale values.
|
|
- Non-finite light or material values.
|
|
- Custom component: invalid type path, invalid field name, empty field expression.
|
|
- Asset reference containing an absolute path, a `..` component or a backslash.
|
|
- With an asset index: referenced sprite image or mesh asset missing, or the wrong asset kind.
|
|
- Sprite `custom_size` with a non-positive component.
|
|
- Text `font_size <= 0`.
|
|
- `PointLight.intensity < 0` or `range <= 0`.
|
|
- `DirectionalLight.illuminance < 0`.
|
|
- An entity is its own parent or introduces a cycle.
|
|
|
|
**Warnings**
|
|
|
|
- Duplicate entity names.
|
|
- A sprite with no image and no custom size (it renders nothing).
|
|
- A zero scale component.
|
|
- Material `metallic` or `perceptual_roughness` outside `0..=1`.
|
|
- Empty `Text2d` string.
|
|
- Both 2D and 3D cameras in one scene.
|
|
- An empty or whitespace-only entity name.
|
|
|
|
**Info**
|
|
|
|
- No camera in the scene.
|
|
- No light in a scene that contains meshes.
|
|
- An entity with only a `Transform`.
|
|
- More than one camera.
|
|
|
|
Validation is deterministic (severity descending, then entity ID, then message) and must not panic
|
|
on malformed forests.
|
|
|
|
## Relationship to BSN
|
|
|
|
The `.forge.ron` file is the source of truth in the editor. Exporting walks the forest and emits
|
|
`Name`, `Transform` and the component list for every entity, converting Euler degrees to a quaternion
|
|
and choosing asset parameters for mesh scenes. The generated file is portable Rust, not a scene asset
|
|
that Bevy loads at runtime. See the [BSN export guide](bsn-export.md).
|