S&box Wiki

Entities

Entities are objects that can be placed within the game world, such as props, players, spawnpoints. They can be created and spawned with the C# API, or automatically as part of a level.

  • Entity is the base class for all entities.

    • RenderEntity extends Entity and can be used for custom rendering.

    • ModelEntity extends Entity and adds support for non-animated models.

      • AnimatedEntity extends ModelEntity and adds support for animated models.

Spawning Entities

Creating a new instance of an Entity class automatically spawns the entity into the world.

Entity myEntity = new MyEntity();

Spawning an Entity calls the virtual method Entity.Spawn() and if replicated on the client Entity.ClientSpawn().

The Spawn method on an entity will be called before its constructor is finished. Related issue: #2282
Entities can be created locally clientside - this will call Entity.Spawn() clientside, but not Entity.ClientSpawn().

Creating with the TypeLibrary

You can also create an instance of an entity by using the TypeLibrary if you have registered the entity by using the [Library] decorator.

[Library("sb_myent", Title = "My Entity")] class MyEntity : Entity { ... } public void SpawnEntity() { MyEntity ent = TypeLibrary.Create<MyEntity>("sb_myent"); }

Events / Overrides

When entities are created and destroyed they are automatically registered to recieve events from the Event System.

partial class MyEntity : Entity { [Event.Tick] void Tick() { Log.Info( $"This is called every tick whilst {this} lives." ); } }

In addition to the event system, entities have plenty of virtual methods you can override, you can use intellisense to find all of them.

public override void Touch( Entity other ) { Log.Info( $"{this} says {other} is touching me." ); }

Networking / Replication

Entities are replicated from the server to clients based on what Entity.Transmit is set to. By default entites are only transmitted to clients that can see them.

partial class MyEntity : Entity { public override void Spawn() { // Always network this entity to all clients Transmit = TransmitType.Always; } }
When an entity is replicated from the server to the client it needs a parameterless constructor to call.

When an entity is replicated any properties marked as a Networked Type are replicated to the entity on the client too.

partial class MyEntity : Entity { [Net] public string MyString { get; set; } }

Components

Entities can have entity components, these are replicated on clients automatically.

partial class MyEntity : Entity { public override Spawn() { Components.Create<MyComponent>(); } }

Hammer and other tools

Entities can be linked to tools such as Hammer. More information about the process can be found on this page

Deleting Entities

Entities are not garbage collected like a normal C# class as they belong to the world. Entities can be explicitly deleted by calling Entity.Delete(), these entities are then invalid and should not be used anymore.

Any reference to a deleted Entity will return false on Entity.IsValid(), you should use this instead of a null check on entities.