<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. ## 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 ``` ⤶ ### Results⤶ ⤶ 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.⤶ ⤶ ## 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" />