S&box Wiki

Revision Difference

Entities#548175

<cat>Code.Entity</cat> 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. [Entity](https://asset.party/api/Sandbox.Entity) is the base class for all entities, [ModelEntity](https://asset.party/api/Sandbox.ModelEntity) extends it to provide a model, [AnimatedEntity](https://asset.party/api/Sandbox.AnimatedEntity) provides animations. [RenderEntity](https://asset.party/api/Sandbox.RenderEntity) can be used for custom rendering. # Spawning Entities Creating a new instance of an Entity class automatically spawns the entity into the world. ```csharp Entity myEntity = new MyEntity(); ``` Spawning an Entity calls the virtual method [Entity.Spawn()](Sandbox.Entity.Spawn) and if replicated on the client [Entity.ClientSpawn()](Sandbox.Entity.ClientSpawn). <warning>The `Spawn` method on an entity will be called before its constructor is finished. Related issue: [#2282](https://github.com/sboxgame/issues/issues/2282)</warning> <note>Entities can be created locally clientside - this will call [Entity.Spawn()](Sandbox.Entity.Spawn) clientside, but not [Entity.ClientSpawn()](Sandbox.Entity.ClientSpawn).</note> ## 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. ```csharp [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](EventSystem). ```csharp 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](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/override), you can use [intellisense](https://docs.microsoft.com/en-us/visualstudio/ide/using-intellisense) to find all of them. ```csharp 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. ```csharp partial class MyEntity : Entity { public override void Spawn() { // Always network this entity to all clients Transmit = TransmitType.Always; } } ``` <note>When an entity is replicated from the server to the client it needs a parameterless constructor to call.</note> When an entity is replicated any properties marked as a [Networked Type](Networked_Types) are replicated to the entity on the client too. ```csharp partial class MyEntity : Entity { [Net] public string MyString { get; set; } } ``` # Components Entities can have [entity components](Entity_Components), these are replicated on clients automatically. ```csharp 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](Linking_Entities_to_Hammer) # 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()](Sandbox.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()](Sandbox.Entity.IsValid), you should use this instead of a null check on entities.