Tutorials
Tutorials
Coming from Godot
If you know Godot, you already think in small reusable pieces, and that carries over to Abyss. What changes is the shape of those pieces: instead of a tree of nodes, each with its own type and script, a game in Abyss is entities that carry components of data, and systems that run over them. This page maps what you know onto Abyss, then walks through the habits worth changing.
The editor
| Godot | Abyss |
|---|---|
| Scene dock | Hierarchy |
| Inspector | Inspector |
| FileSystem dock | Project |
| 2D and 3D viewports | The Scene panel, with its 2D switch |
| Running the game in its own window | Play (Ctrl+P), in the Game panel |
| Output | Logs |
| Project Settings, Editor Settings | Edit ▸ Project Settings, Edit ▸ Preferences |
| Export | File ▸ Build Settings (Ctrl+Shift+B) |
| AssetLib | Window ▸ Package Manager, with the Store on abyssengine.net |
The editor's windows tours every panel.
The model: entities and components, not nodes
| Godot | Abyss |
|---|---|
| A node | An entity: an id that components are attached to |
| A node's type (Sprite2D, Camera3D, CharacterBody2D) | Components on an entity: Sprite, Camera, Character Controller 2D. An entity carries as many as it needs |
| A script attached to a node | A component for the data, and a system for the behavior |
@export variables | A component's fields, shown in the Inspector |
_process(delta) | A system: it runs every frame over every entity with the components it asks for |
_physics_process(delta) | A system marked [AbyssSystem(Fixed = true)] |
_ready() | A plugin's Build, its Started hook, or a flow |
await on a timer or signal | A flow: an async method that awaits frames, seconds or loads |
| Autoloads | Resources, structs the world holds once, and services for objects |
| Groups | A component the entities carry, which a system's query asks for |
| The node tree | Entities have parents too, shown as a tree in the Hierarchy; a child moves with its parent |
In Godot, a script extends a node and both holds its data and acts on it. In Abyss those are two things. The component says what an entity is:
[AbyssComponent]public partial struct Mover{ public float Speed = 2f; // meters a second}The system says what happens to every entity that has it, once a frame, as _process would:
public static partial class Moving{ [AbyssSystem] [MethodImpl(MethodImplOptions.AggressiveInlining)] private static void Move(ref Transform transform, in Mover mover, in SystemContext context) { transform.TranslationX += mover.Speed * context.DeltaTime; }}A plugin adds the system once, and it runs over every mover in the game. Entities, components and systems explains the model, and C# in a game shows how each piece is written.
Code is C#, with .NET 10. A game can also add Rust beside it, since the engine is built on Bevy; see Rust in a game.
Components hold data only
A component is an unmanaged struct: numbers, vectors, enums, fixed-size text and lists, and references written as ids. It cannot hold a string, an array or an object. In return, the engine stores components packed together, and the Inspector, scenes and prefabs read them with no serialization code.
| Godot | Abyss |
|---|---|
@export_range(0, 10) | [Range(0f, 10f)] on the field |
| A tooltip from a doc comment | [Tooltip("...")] on the field |
@export var target: Node3D | An EntityRef field, a slot you drag an entity onto |
@export var enemy: PackedScene | A PrefabRef field |
@export var stats: Resource | An AssetRef<T> field, for a data asset |
Scenes and prefabs
A Godot scene does two jobs, a level and a reusable part, and Abyss names them apart:
| Godot | Abyss |
|---|---|
| A scene you play: a level, a menu | A scene, a .scene file |
| A scene you instance into others: a player, an enemy, a coin | A prefab |
| Inherited scenes | Variants: a prefab that is another with changes, and follows it |
| Editable children, values changed on an instance | Overrides, marked in the Inspector, with Revert and Apply |
preload("res://enemy.tscn").instantiate() | context.Commands.Instantiate(prefab, position, rotation) |
queue_free() | context.Commands.Despawn(entity) |
get_tree().change_scene_to_file(...) | context.Scenes.Load(key), which loads a slice at a time and never freezes a frame |
Drag an entity into the Project panel to make it a prefab, and drag the prefab into a scene to place an instance. Scenes and prefabs covers both.
Assets and loading
| Godot | Abyss |
|---|---|
res:// paths | Files in the project's assets folder, each with a .abyss sidecar holding its identity, so moving a file breaks nothing |
.import files | The same .abyss sidecars, which hold a file's import settings |
Resources (.tres) of your own classes | Data assets: a struct marked [DataAsset], made from the Project panel |
| Custom project settings | A struct marked [ProjectSettings], a page of Project Settings |
ConfigFile in user:// | Preferences: typed classes marked [Preferences], read through world.Preferences |
load("res://...") | Load by a typed key the build writes: context.Assets.LoadPrefab(Addresses.Enemy) |
Mark an asset Addressable in its Inspector to give it an address and labels. The build writes a key for each, so a path that changes stops the build at the line that uses it, rather than failing as the game plays. See Assets, identities and addresses.
Features you know, by their Abyss names
| Godot | Abyss |
|---|---|
| InputMap, actions | Input actions in settings/input.json, edited on Project Settings' Input page; see Input actions |
| Sprite2D, AnimatedSprite2D | Sprite, and clips made from a sprite sheet; see Sprites |
| TileMapLayer, TileSet | Tilemap and the Tile Palette panel; see Tilemaps |
| Camera2D with smoothing and limits, ParallaxBackground | Camera Follow 2D and Parallax 2D; see 2D cameras |
| PointLight2D, LightOccluder2D | 2D lights; see 2D lights |
| CharacterBody2D, RigidBody2D, Area2D, CollisionShape2D | Character Controller 2D, Rigidbody 2D, trigger colliders and colliders, in the Physics 2D package; see Bodies and colliders |
| The same in 3D | The Physics 3D package; see Bodies and colliders |
| NavigationRegion3D, NavigationAgent3D | Nav Mesh Surface 3D and Nav Mesh Agent 3D, in the Navigation package; see Navmeshes |
| AnimationPlayer, AnimationTree | Animation clips and the Animation window; the Animator and its controller; see The Animator |
| GPUParticles, CPUParticles | Particle Emitter; see Particle Emitter |
| Control nodes, Themes | UI documents and style sheets; see UI documents and controls |
| AudioStreamPlayer, audio buses | Audio Source, and the buses of the Audio panel; see Sounds and audio sources |
print() | Log.Info, Log.Warning, Log.Error, shown in Logs |
@tool scripts | A plugin marked [ExecuteAlways], whose systems also run while editing |
| Editor plugins | An [EditorOnly] plugin: Scene view handles, Inspector notes, menu items and windows |
| Web export | Web builds, from Build Settings; see Build and run your game |
Things that work differently
No signals. Systems do not call each other. A system reads what happened from data: a component another system wrote, the contacts physics reports, the clicks a UI reports, or the events an animation fires (context.Events<T>()). What would be a signal connected to one node is usually a field, set by one system and read by another.
2D is Y up. Abyss uses Bevy's coordinates in 2D and 3D alike: +X right, +Y up, and +Z toward the viewer. In Godot's 2D, +Y goes down. In 3D they agree: right-handed, +Y up, a camera with no rotation looking along -Z. Lengths are in world units: meters in 3D, and in 2D a sprite is as many units across as its pixels divided by its image's Pixels Per Unit.
Rotation is a quaternion. A Transform keeps its rotation as a quaternion's four numbers, RotationX to RotationW. Build a System.Numerics.Quaternion from them to work with it, and write its four numbers back. The Inspector shows the rotation as angles in degrees.
Order is explicit. Systems run in the order your plugins add them, and schedule.RunBefore states an order between two systems. A tree's order decides nothing.
Changes during a frame are commands. A system cannot spawn or remove entities while it runs. It records commands, which the engine applies once the frame's systems have run. See Changing the world.
Each Play starts afresh. Every Play loads your C# again, as a built game starts, and Stop puts the scene back as it was at Play.
Where to go next
- A first 2D game builds a small game step by step.
- Entities, components and systems is the one page to read before writing code.
- C# in a game covers components, systems, plugins, settings and data assets.
