<cat>Dev.Entities</cat> <title>Creating Custom Entities/Entity</title> ⤶ #Creating a Custom Entity/Entities in Garry's Mod ## 1. Introduction Custom entities in Garry's Mod offer a way to enhance gameplay and developer flexibility by allowing creators to introduce unique elements, behaviors, and interactions into their games. These entities can range from simple, static models in the game world to complex, interactive objects that can interact with players and other entities in various ways. The ability to create custom entities opens up endless possibilities for game customization, making it a vital skill for any Garry's Mod developer aiming to craft engaging and dynamic game environments. ⤶ ## 2. Fundamentals⤶ ### Basic Definitions⤶ - Entities: In Garry's Mod, entities are objects in the game world. (For the most part) ### Key Components⤶ - Initialization: The process of setting up an entity's default state. - Logic Handling: The code that determines an entity's behavior and responses to game events. - Shared Configuration: Defines properties across server and client. ## 3. Setting Up the Environment⤶ ### Workspace Preparation⤶ - Familiarize yourself with the game's file system, especially the lua/entities directory where custom entities are stored. ⤶ ##### Gamemode:⤶ ⤶ # 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. * **Shared** - Configuration and properties available to both Server and Client Realms. * **Server** - Controling the Entity's behavior and interactions. ⤶ ## 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/ └── mygamemode/⤶ ├── entities/ │ ├── entities/ │ │ └── testent/⤶ │ │ ├── cl_init.lua⤶ │ │ ├── init.lua⤶ │ │ └── shared.lua⤶ ├── 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⤶ ``` ##### Addon:⤶ 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⤶ ``` addons/⤶ └── myaddon/⤶ ├── lua/⤶ │ ├── autorun/⤶ │ │ └── myaddon_autorun.lua⤶ │ ├── entities/⤶ │ │ └── testent/⤶ │ │ ├── cl_init.lua⤶ │ │ ├── init.lua⤶ │ │ └── shared.lua⤶ ⤶ ```⤶ ### Tools and Resources⤶ - [VSCode](https://code.visualstudio.com) or any preferred Lua editor for writing and editing code.⤶ - [Video: "Ep. 13 Creating An Entity #1" by Codeblue](https://www.youtube.com/watch?v=uE5A4AwwIK8)⤶ - [Video: "Ep. 14 Creating An Entity #2" by Codeblue](https://www.youtube.com/watch?v=rjgXF9gqiCU)⤶ - [Video: "Ep. 25 Advanced Entity Example" by Codeblue](https://www.youtube.com/watch?v=Kr3xM6sgduA)⤶ ## 4. Creating an entity⤶ - Create the Entity Files: Start by creating a folder with the addon or gamemode folder, `lua/entities` for your entity. Inside, create another folder, of the name of your entity e.g `testent`. It should look like this `lua/entities/testent`, then create three lua files: `shared.lua`, `cl_init.lua`, and `init.lua`.⤶ - Define the Entity: In shared.lua, define basic properties like entity type, base, and print name.⤶ - Server-Side Setup: Use init.lua to define server-side logic, such as model, physics, and initialization behavior.⤶ - Client-Side Setup: cl_init.lua handles client-side aspects, primarily drawing the entity model.⤶ ⤶ ### 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.⤶ ⤶ ## 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. 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⤶ ⤶ #### init.lua example:⤶ ⤶ ```lua⤶ AddCSLuaFile("cl_init.lua") AddCSLuaFile("shared.lua") include("shared.lua") -- Server-side initialization function for the entity⤶ -- 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. 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.). phys:Wake() -- Activates the physics object, making the Entity subject to physics (gravity, collisions, etc.). end end ``` ### cl_init.lua example: ```lua⤶ ⤶ #### cl_init.lua example: ⤶ ```lua⤶ include("shared.lua") -- Client-side draw function for the entity⤶ -- Client-side draw function for the Entity⤶ function ENT:Draw() self:DrawModel() -- Draws the model of the entity. This function is called every frame. self:DrawModel() -- Draws the model of the Entity. This function is called every frame. end ``` ⤶ The structure should look like this⤶ ```⤶ └── lua⤶ └── entities⤶ └── testent⤶ ├── cl_init.lua⤶ ├── init.lua⤶ └── shared.lua⤶ ```⤶ ⤶ ### Result:⤶ <upload src="b5453/8dc30024d6e1a37.png" size="15705" name="image.png" />⤶ ### 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⤶ ⤶ 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" />⤶ ⤶