<cat>Dev.Modding</cat> <title>Entities</title> # How To Spawn ## Prefab Name ___ The prefab name represents the full path of the prefab inside the game files. It always starts with `assets/` and will be fully lowercase. ## Position ___ The position in the world where the entity will be placed. The default position is 0,0,0. This represents the the center of the map at water level. ## Rotation ___ The rotation of the entity after being spawned. `There will be a section on Quaternions later, but simplified explaination here for now:` There are there axis: * The X axis goes from your left to right. * The Y axis goes from above to below you. * The Z axis goes from front to back. Your rotation can be represented by your rotation by turning each axis, which leads to the following behaviour: * X rotation = leaning forward and backwards * Y rotation = turning left and right * Z rotation = tilting left and right This means you represent your rotation as 3 numbers: `( 'x' rotation, 'y' rotation, 'z' rotation )`. These are called `Euler` (aka `Human readable`) angles. However there is one catch: Internally a `Quaternion` represents your rotation as 4 numbers which makes the math easier for a computer but near impossible to understand as a human. To solve this problem we have helper functions. You can use `Quaternion.Euler(x,y,z)` to create a new `Quaternion` rotation based on the `Euler` angles. If you want to convert an existing rotation back to the `Euler` angles just use `.eulerAngles` on a rotation. ```csharp //Create a new rotation that is 45° to the left Quaternion rotation = Quaternion.Euler(0,45,0); //Turn the rotation back to human readable Console.WriteLine( rotation.eulerAngles ); > Prints (0, 45, 0) ``` The code to spawn an entity will make a lot more sense now that we know what all the parameters mean. # Code To Spawn Entity The first part of spawning something is to create the entity. The function takes the 3 parameters described above into this function: ```csharp GameManager.server.CreateEntity(string prefabName, Vector3 position, Quaternion rotation) ``` We store the result in a variable of type BaseEntity. If there was an error spawning the entity or an invalid prefab name was supplied the entity will be `null`. We should check for this before calling the `Spawn()` function or we risk throwing an error. A full example follows. ``` BaseEntity rowBoat = GameManager.server.CreateEntity( "assets/content/vehicles/boats/rowboat/rowboat.prefab", new Vector3( 450, 0, 1000), Quaternion.Identity( 0, 90, 0) ); if (rowBoat == null) { return; } //Don't forget to call spawn after rowBoat.Spawn(); ``` # How To Delete An Entity After you have spawn your boat your going to want to remove it. You could look at the boat on the client, run `ent kill` in the F1 Console and it would be removed. But what if we want to automate it? Lets continue with the example above: ```csharp BaseEntity rowBoat = GameManager.server.CreateEntity("assets/content/vehicles/boats/rowboat/rowboat.prefab"); if ( rowBoat != null ) { rowBoat.Spawn(); } //Now we want to remove it //Obviously the entity won't be null in this example but for longer running code you might want to check this if ( rowBoat != null ) { if ( rowBoat.IsDestroyed == false ) { rowBoat.Kill(); } } ``` Hold on, why did we check this `IsDestroyed` variable and what does it mean?⤶ ⤶ ⤶ # What is 'IsDestroyed'⤶ ⤶ The bool `IsDestroyed` lets you know if the entity has been already removed by the game. ⤶ ⤶ This is needed because the entity does **not** go `null` after you `Kill()` it. ⤶