<cat>Dev.Entities</cat> <title>Creating Custom Entities/Entity</title> # Creating a Custom Entity in Garry's Mod ## Introduction ### What are Entities? Nearly everything you can see and touch in Garry's Mod is an <page>Entity</page>. Any object with a position in the game world is an Entity. The <page>Player</page> is an Entity, props are Entities, even the the <page text="Game World">game.GetWorld</page> itself is an Entity—albiet a special and unique one. Entities are able to have custom, developer-defined behaviors that can control things like the way they look and the way they can be interacted with. Entities are often foundational parts of <page text="Gamemodes">Gamemode_Creation</page> and <page>Addons</page> ### What are the components of an Entity? Entities have aspects in all 3 <page text="Realms">States</page>: * **Client** - Drawing/Rendering the Entity. * **Server** - Controling the Entity's behavior and interactions. * **Shared** - Configuration and properties available to both Server and Client Realms. Shared isn't actually a Realm. It only means that both Client and Server will run the same code that's in a Shared file. Shared isn't really a Realm. It only means that both Client and Server will run the same code that's in a Shared file. ## Setup ### File Location The file(s) that make up an Entity should be placed either in an Addon or in a Gamemode. #### Addon Entity Location ``` addons/ ├── my-addon-name/ │ ├── lua/ │ │ ├── entities/ │ │ │ └── ... ``` #### Gamemode Entity Location ``` gamemodes/ ├── my-gamemode-name/ │ ├── entities/ │ │ ├── entities/ │ │ │ └── ... ``` ### File Structure Entities can be created either using * 3 separate files that each contain one Realm's code and configuration. * This approach helps with code organization. * The name of the folder containing these files (`my-entity-name` in the example below) will be used as the Entity's <page text="Class Name">Entity:GetClass</page>. * The files are: * `cl_init.lua` * The Client Realm * `init.lua` * The Server Realm * `shared.lua` * The Shared Realm ``` entities/ ├── my-entity-name/ │ ├── cl_init.lua │ ├── init.lua │ └── shared.lua ``` * 1 file containing all the code and configuration for all 3 Realms. * This approach is primarily useful when creating simple entities. * The file's name (`my-entity-name` in the example below) will be used as the Entity's Class Name. ``` entities/ ├── my-entity-name.lua ``` ## Creating an Entity ### Creating an Entity with separate files #### shared.lua example: ```lua -- Defines the Entity's type, base, printable name, and author for shared access (both server and client) ENT.Type = "anim" -- Sets the Entity type to 'anim', indicating it's an animated Entity. ENT.Base = "base_gmodentity" -- Specifies that this Entity is based on the 'base_gmodentity', inheriting its functionality. ENT.PrintName = "Test Entity" -- The name that will appear in the spawn menu. ENT.Author = "YourName" -- The author's name for this Entity. ENT.Category = "Test entities" -- The category for this Entity in the spawn menu. ENT.Contact = "STEAM_0:1:12345678" -- The contact details for the author of this Entity. ENT.Purpose = "To test the creation of entities." -- The purpose of this Entity. ENT.Spawnable = true -- Specifies whether this Entity can be spawned by players in the spawn menu. ``` #### init.lua example: ```lua AddCSLuaFile("cl_init.lua") AddCSLuaFile("shared.lua") include("shared.lua") -- Server-side initialization function for the Entity function ENT:Initialize() self:SetModel( "models/hunter/blocks/cube025x025x025.mdl" ) -- Sets the model for the Entity. self:PhysicsInit( SOLID_VPHYSICS ) -- Initializes physics for the Entity, making it solid and interactable. self:SetMoveType( MOVETYPE_VPHYSICS ) -- Sets how the Entity moves, using physics. self:SetSolid( SOLID_VPHYSICS ) -- Makes the Entity solid, allowing for collisions. local phys = self:GetPhysicsObject() -- Retrieves the physics object of the Entity. if phys:IsValid() then -- Checks if the physics object is valid. phys:Wake() -- Activates the physics object, making the Entity subject to physics (gravity, collisions, etc.). end end ``` #### cl_init.lua example: ```lua include("shared.lua") -- Client-side draw function for the Entity function ENT:Draw() self:DrawModel() -- Draws the model of the Entity. This function is called every frame. end ``` ### Creating an Entity with a single file ```lua AddCSLuaFile() -- Defines the Entity's type, base, printable name, and author for shared access (both server and client) ENT.Type = "anim" -- Sets the Entity type to 'anim', indicating it's an animated Entity. ENT.Base = "base_gmodentity" -- Specifies that this Entity is based on the 'base_gmodentity', inheriting its functionality. ENT.PrintName = "Test Entity" -- The name that will appear in the spawn menu. ENT.Author = "YourName" -- The author's name for this Entity. ENT.Category = "Test entities" -- The category for this Entity in the spawn menu. ENT.Contact = "STEAM_0:1:12345678" -- The contact details for the author of this Entity. ENT.Purpose = "To test the creation of entities." -- The purpose of this Entity. ENT.Spawnable = true -- Specifies whether this Entity can be spawned by players in the spawn menu. -- This will be called on both the Client and Server realms function ENT:Initialize() -- Ensure code for the Server realm does not accidentally run on the Client if SERVER then self:SetModel( "models/hunter/blocks/cube025x025x025.mdl" ) -- Sets the model for the Entity. self:PhysicsInit( SOLID_VPHYSICS ) -- Initializes physics for the Entity, making it solid and interactable. self:SetMoveType( MOVETYPE_VPHYSICS ) -- Sets how the Entity moves, using physics. self:SetSolid( SOLID_VPHYSICS ) -- Makes the Entity solid, allowing for collisions. local phys = self:GetPhysicsObject() -- Retrieves the physics object of the Entity. if phys:IsValid() then -- Checks if the physics object is valid. phys:Wake() -- Activates the physics object, making the Entity subject to physics (gravity, collisions, etc.). end end end -- This is a common technique for ensuring nothing below this line is executed on the Server if not CLIENT then return end -- Client-side draw function for the Entity function ENT:Draw() self:DrawModel() -- Draws the model of the Entity. This function is called every frame. end ``` Not sure what any of these do? Feel free to click on any of the blue <page text="functions">Global.AddCSLuaFile</page>() to find out. <page>ENTITY:Initialize</page>() and <page>ENTITY:Draw</page>() are considered <page text="Hooks">ENTITY_Hooks</page>. These aren't clickable in the above examples, but you can search for hooks by typing ` is:event` (two spaces) into the top left of this page. Whenever these Hooks are called by the game, the code that you wrote in them will be ran on your Entity. They're typed <page text="ENT">Structures/ENT</page> here in order to register your entity's object class. Whenever these Hooks are called by the game, your Entity runs the code you’ve defined for them. They're typed <page text="ENT">Structures/ENT</page> here in order to register your entity's object class. ## Results Regardless of whether you've created the Entity with one file or several, the final result should be the same. #### The Entity in the spawn menu <image src="b5453/8dc30024d6e1a37.png" size="15705" name="image.png" /> #### The Entity itself <image src="b2b4c/8dcdcb3082d6ccc.png" size="588581" name="image.png" />