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

UnityAbyss
Hierarchy, Inspector, Project, Scene and Game viewsHierarchy, Inspector, Project, Scene and Game panels, in the same places by default
ConsoleLogs
W, E, R, T tools; F frames the selection; Ctrl+D duplicates; Ctrl+P playsThe same keys
GameObject menuEntity menu
Project Settings, Preferences, Build SettingsEdit ▸ Project Settings, Edit ▸ Preferences, File ▸ Build Settings (Ctrl+Shift+B)
Package Manager, Asset StoreWindow ▸ Package Manager, with the Store on abyssengine.net
Unity HubThe Abyss Hub, which installs editors and makes projects

The editor's windows tours every panel.

The model: entities, not GameObjects

UnityAbyss
GameObjectAn entity: an id that components are attached to
A component on a GameObjectA component: a plain struct of data, with no methods
MonoBehaviour.UpdateA system: a function that runs every frame over every entity with the components it asks for
FixedUpdateA system marked [AbyssSystem(Fixed = true)]
Start and AwakeA plugin's Build, its Started hook, or a flow (see below)
A coroutineA flow: an async method that awaits frames, seconds or loads
A singleton managerA resource, a struct the world holds once, or a service for an object
GetComponent<T>()Ask for T in the system's parameters
A tagA component the entities carry, which a system's query asks for
LayersLayers, 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:

AttributeWhere 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.

UnityAbyss
Instantiate(prefab, position, rotation)context.Commands.Instantiate(prefab, position, rotation)
Destroy(gameObject)context.Commands.Despawn(entity)
SceneManager.LoadSceneAsynccontext.Scenes.Load(key, SceneMode.Additive), which never freezes a frame
A scene in a build's listFile ▸ 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

UnityAbyss
.meta files and GUIDs.abyss sidecars with each file's identity
AddressablesEvery 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.LoadNo equivalent: give the asset an address, or name it in a component's slot
ScriptableObjectA data asset: a struct marked [DataAsset], made from the Project panel
Custom Project SettingsA struct marked [ProjectSettings], a page of Project Settings
PlayerPrefsPreferences: 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

UnityAbyss
Input System, its action maps and bindingsInput actions in settings/input.json, edited on Project Settings' Input page; see Input actions
Rigidbody and collidersRigidbody 3D and its colliders, in the Physics 3D package; see Bodies and colliders
Rigidbody2D and 2D collidersRigidbody 2D and its colliders, in the Physics 2D package; see Bodies and colliders
CharacterControllerCharacter Controller 3D and Character Controller 2D
NavMesh, NavMeshAgentNav Mesh Surface 3D and Nav Mesh Agent 3D, in the Navigation package; see Navmeshes
Animator, Animator Controller, Animation windowThe Animator, its controller in the Animator panel, and the Animation window; see The Animator
Particle System, Trail Renderer, Line RendererParticle Emitter, Trail and Line; see Particle Emitter
Sprite Renderer, Sprite Editor, Sorting LayersSprite, the Sprite Editor, Sorting Layer and Order in Layer; see Sprites
Tilemap and Tile PaletteTilemap and the Tile Palette panel; see Tilemaps
2D lights, Pixel Perfect Camera, Cinemachine for 2D2D lights, Pixel Perfect Camera and Camera Follow 2D; see 2D lights and 2D cameras
UI Toolkit, UXML and USSUI documents and style sheets; see UI documents and controls
AudioSource, AudioMixerAudio Source and the buses of the Audio panel; see Sounds and audio sources
ProfilerWindow ▸ Profiler
Debug.LogLog.Info, Log.Warning, Log.Error, shown in Logs
Gizmos, OnDrawGizmoscontext.Gizmos, from a system in an [EditorOnly] plugin
Editor scripts, custom menus and windowsAn [EditorOnly] plugin: Scene view handles, Inspector notes, menu items and windows
WebGL buildsWeb 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