Tutorials
Tutorials
Coming from Unity
If you know Unity, most of Abyss will feel familiar: the editor's panels sit where you expect them, prefabs work as you know them, and many of the shortcuts are the same. The difference is underneath: a game in Abyss is entities, components that hold only data, and systems that run over them. This page maps what you know onto Abyss, then walks through the habits worth changing.
The editor
| Unity | Abyss |
|---|---|
| Hierarchy, Inspector, Project, Scene and Game views | Hierarchy, Inspector, Project, Scene and Game panels, in the same places by default |
| Console | Logs |
| W, E, R, T tools; F frames the selection; Ctrl+D duplicates; Ctrl+P plays | The same keys |
| GameObject menu | Entity menu |
| Project Settings, Preferences, Build Settings | Edit ▸ Project Settings, Edit ▸ Preferences, File ▸ Build Settings (Ctrl+Shift+B) |
| Package Manager, Asset Store | Window ▸ Package Manager, with the Store on abyssengine.net |
| Unity Hub | The Abyss Hub, which installs editors and makes projects |
The editor's windows tours every panel.
The model: entities, not GameObjects
| Unity | Abyss |
|---|---|
| GameObject | An entity: an id that components are attached to |
| A component on a GameObject | A component: a plain struct of data, with no methods |
MonoBehaviour.Update | A system: a function that runs every frame over every entity with the components it asks for |
FixedUpdate | A system marked [AbyssSystem(Fixed = true)] |
Start and Awake | A plugin's Build, its Started hook, or a flow (see below) |
| A coroutine | A flow: an async method that awaits frames, seconds or loads |
| A singleton manager | A resource, a struct the world holds once, or a service for an object |
GetComponent<T>() | Ask for T in the system's parameters |
| A tag | A component the entities carry, which a system's query asks for |
| Layers | Layers, on the Tags and Layers page of Project Settings |
In Unity a script both holds a GameObject's 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:
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 then runs over a thousand movers as cheaply as over one. Entities, components and systems explains the model, and C# in a game shows how each piece is written.
No component is mandatory, the Transform included: an entity that is only data, such as a score keeper, carries no Transform.
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, a List<T> or a reference to another object. In return, the engine stores components packed together, and the Inspector, scenes and prefabs read them without any serialization code.
What you would have written as fields still looks the same, and these attributes keep their Unity names and meanings:
| Attribute | Where it goes |
|---|---|
[Range], [Tooltip], [HideInInspector] | A component's field |
[FormerlySerializedAs] | A renamed field, or on the struct for a renamed component |
[ExecuteAlways] | A plugin whose systems run while editing too |
[ColorUsage] | A Vector3 or Vector4 shown as a color |
There is no [SerializeField]: every field of a component is saved, public or not.
References to other things are fields of their own types: PrefabRef for a prefab, EntityRef for another entity, AssetRef<T> for a data asset and FileRef for any other file. Each shows a slot in the Inspector that you drag onto.
Prefabs and scenes
Prefabs work as you know them: drag an entity to the Project panel to make one, drag one into the scene for an instance, edit it on its own, override values on an instance, make variants, and nest instances. Overrides are marked the same way and reverted from the same places. Scenes and prefabs covers them, and how a game loads scenes while it plays.
| Unity | Abyss |
|---|---|
Instantiate(prefab, position, rotation) | context.Commands.Instantiate(prefab, position, rotation) |
Destroy(gameObject) | context.Commands.Despawn(entity) |
SceneManager.LoadSceneAsync | context.Scenes.Load(key, SceneMode.Additive), which never freezes a frame |
| A scene in a build's list | File ▸ Build Settings, the scenes in the build |
A model you import is a prefab, as in Unity, and its import settings (scale, normals, skeleton, clips, materials) are in the Inspector with Apply and Revert.
Assets and loading
| Unity | Abyss |
|---|---|
.meta files and GUIDs | .abyss sidecars with each file's identity |
| Addressables | Every asset can be Addressable, with an address and labels |
Addressables.LoadAssetAsync<T>("key") | context.Assets.LoadPrefab(Addresses.Enemy): a typed key the build writes |
Resources.Load | No equivalent: give the asset an address, or name it in a component's slot |
| ScriptableObject | A data asset: a struct marked [DataAsset], made from the Project panel |
| Custom Project Settings | A struct marked [ProjectSettings], a page of Project Settings |
| PlayerPrefs | Preferences: typed classes marked [Preferences], read through world.Preferences |
Loading by a string is a build error: an address that changes, or an asset no longer addressable, stops the build at the line that uses it. See Assets, identities and addresses.
Features you know, by their Abyss names
| Unity | Abyss |
|---|---|
| Input System, its action maps and bindings | Input actions in settings/input.json, edited on Project Settings' Input page; see Input actions |
| Rigidbody and colliders | Rigidbody 3D and its colliders, in the Physics 3D package; see Bodies and colliders |
| Rigidbody2D and 2D colliders | Rigidbody 2D and its colliders, in the Physics 2D package; see Bodies and colliders |
| CharacterController | Character Controller 3D and Character Controller 2D |
| NavMesh, NavMeshAgent | Nav Mesh Surface 3D and Nav Mesh Agent 3D, in the Navigation package; see Navmeshes |
| Animator, Animator Controller, Animation window | The Animator, its controller in the Animator panel, and the Animation window; see The Animator |
| Particle System, Trail Renderer, Line Renderer | Particle Emitter, Trail and Line; see Particle Emitter |
| Sprite Renderer, Sprite Editor, Sorting Layers | Sprite, the Sprite Editor, Sorting Layer and Order in Layer; see Sprites |
| Tilemap and Tile Palette | Tilemap and the Tile Palette panel; see Tilemaps |
| 2D lights, Pixel Perfect Camera, Cinemachine for 2D | 2D lights, Pixel Perfect Camera and Camera Follow 2D; see 2D lights and 2D cameras |
| UI Toolkit, UXML and USS | UI documents and style sheets; see UI documents and controls |
| AudioSource, AudioMixer | Audio Source and the buses of the Audio panel; see Sounds and audio sources |
| Profiler | Window ▸ Profiler |
| Debug.Log | Log.Info, Log.Warning, Log.Error, shown in Logs |
| Gizmos, OnDrawGizmos | context.Gizmos, from a system in an [EditorOnly] plugin |
| Editor scripts, custom menus and windows | An [EditorOnly] plugin: Scene view handles, Inspector notes, menu items and windows |
| WebGL builds | Web builds, from Build Settings; see Build and run your game |
Things that work differently
The axes. Abyss uses Bevy's coordinates: right-handed, with +Y up, +X to the right, and +Z toward the viewer, so a camera with no rotation looks along -Z. Unity is left-handed with +Z forward. A model you import is converted for you; code that builds vectors by hand should use -Z as forward. Lengths are in meters.
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. Unity calls every Update in an order you rarely control. Abyss runs systems in the order your plugins add them, and schedule.RunBefore states an order between two systems. There is no LateUpdate: add the system later, or order it after the one it follows.
No null objects. Entities are ids, not objects. Removing one leaves nothing behind to check for null: the systems' queries simply stop finding it.
Changes during a frame are commands. A system cannot spawn or remove entities while it runs. It records commands, and the engine applies them once the frame's systems have run. See Changing the world.
Each Play starts afresh. As in Unity with domain reload on, every Play loads your C# again, so a static field starts at its initializer. Stop puts the scene back as it was at Play.
Rust is there if you need it. The engine is Bevy, and a game can add Rust code of its own beside its C#. See Rust in a game.
Where to go next
- A first 3D 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.
