MAC's NPCs v1.3 + Documentation (ENG)

Basic Setup

1. To install this addon to your server just unzip all folders to your garrysmod/addons folder and restart the server.

Note: This addon will contain two folders mc_simple_npcs and mcd_ui which both must be placed inside your addon folder. If you already have mcd_ui addon, you can skip or update the files, as it was downloaded with my other products.

2. To start setting up an NPC enter the server. Open the game console and type the mcs_setup command to open the setup menu. Note: In order to open you must have superadmin privilege on your server

In the setting tab, you can do all configurations. To do it manually edit sh_config.lua file located in mc_simple_npcs/lua/mcs_npcs

This menu features autosave on close and autoloads last edited NPC

NPC setup

NPC Name

NPC’s Name will be displayed above it and inside the dialogue box. Example:

Unique ID

In this text box, you must enter the unique name for the NPC. It used only by the server and it must be unique for each NPC you create. It will also be used as a name for the save file.

NPC Name position

In this text box, you can adjust the height of the NPC’s name displayed above his head. This can be useful if you use bigger or smaller models. Read more about it in the advanced setup

Use limitation

By checking this option only one player will be able to use the NPC. This is option is needed if you want to use animation playback in the dialog. See more at The Dialogue setup

Dialogue theme

Here you can change the dialogue UI themes from the list of supported themes. This will affect only the NPC you are editing.

Note: Currently supported themes - Default, Retro, Backbone, Hollow Knight.

Model and animation setup

To set a model for your NPC, copy and paste the path to the model inside the text box. You can use the Copy from looking entity button to copy the model path from the entity you looking at.

You can adjust the NPC model size by dragging the Scale slider. 100% scale will use original model size, 200% doubles it in size, 50% makes it half the original model size.

You can preview the model on the side panel, rotate it, and zoom by double-clicking it. If your model supports body groups or skins you will see these panels for adjustment.

To make your NPC animated, enter the animation name inside the “NPC animation” text box.

By pressing the Get animations button you’ll see a list of all animations for the model you use. By pressing on one of them you’ll be able to preview it and it will be automatically set

For more info about how to get the animations, you can look inside the old documentation (3.5 Animations).

Spawn position

The spawn position for the current map will be created automatically if there is no one.

To set spawn position press one of the 3 buttons.

The Set to your position button will copy your current position.
The Set to looking point button will copy position from your aiming point.
The Copy from looking entity button will copy position from the entity you are looking at if there is any.

For the manual corrections later see Advanced setup

 

Dialogue setup

To create a dialog for the NPC navigate to the Dialogue setup tab

For a new dialogue line press the Add new line button. This will add a new panel to the list. Click the panel to edit the dialogue line.

Each line will have its own ID displayed. Line with ID 1 will be opened first every time player speaks to the NPC.

In the first text box, you can enter NPC’s speech, it supports the newline ( \n ) operator.

Inside the Sound: text box you can optionally enter the path to the sound that will be auto-played when the player opens this dialogue line. Example in the video

To add more answers that the player can choose, press the Add answer line button on the right. To remove the answer press the Remove answer button. If there are no answers, the “...” answer with the close option will be added automatically.

Each answer you create can do two basic things, close the dialogue or open the line with the ID you will choose in the drop-down menu (by pressing on the Action button).

If your server uses addons that are supported by “Simple NPCs” you will see the addon’s name in the list. By selecting an addon from the list, the answer will do an action from the addon you chose.

To add a playback animation, when you choose an answer (like on this video) you can enter the animation name in the text box after the Action button. To quickly browse all available animations for the model go to the NPC setup tab and use the Get animations button, which will open a list of all animations.

Note: The checkbox for use limitation must be checked on (see Use limitations).

Tip: For big and complicated dialogues we recommend creating a doc file with dialogue structure before starting setting up the NPCs

Final setup

Navigate to the Final setup tab, to save NPC preset and copy the Lua code for the NPC.

Saving NPC

To save the NPC press the Copy NPC Lua code button at the top

Then open sh_npcspawn.lua inside mc_simple_npcs/lua/mcs_npcs and paste NPC’s code to the bottom of the file.

To replace or remove an existing NPC just select the whole NPC table and remove it.

NPCs will automatically spawn on server startup, or you can respawn them by pressing the Respawn all NPCs button or typing the  mcs_npcrespawn command in the console.

The Save NPC preset and Open NPC preset buttons will help you to save NPC presets and open them when you need to edit any of the NPCs without editing Lua file.

The New NPC preset button will just create a blank NPC.

Advanced Setup

Note. In advanced setup mostly we will be working with an existing NPC table and you will need lua knowledge to do this correctly.

NPC Table structure:

MCS.Spawns["uid"] = { // uid - the unique id for an NPC
    name = "Name",  // NPC's name will be shown to players above the NPC and via the dialogue.
    model = "models/path/npc.mdl", // Path to the model
    scale = 1, // NPC model scale (size), 1 - normal, 2 - 2 times bigger, 0.5 - 2 times smaller
    uselimit = false, // Allow only one player to speak to the npc at the same time
    theme = "Theme Name",  // Dialogue theme. Currently supported themes - Default, Retro, Hollow Knight
    pos = {
         ["map_name"] = {Vector(0,0,0), Angle(0,0,0)}, // spawn position filter by maps
         ["all"] = {Vector(0,0,0), Angle(0,0,0)}, // use 'all' to spawn npc any way, even if there is no map in this table
    },
    bgr = {
        [1] = 2,
        [2] = 0,
    }, // Table of bodygroups [The id of the bodygroup you're setting. Starts from 0] = The value you're setting the bodygroup to. Starts from 0
    skin = 1, // Sets the skin of the entity
    namepos = 30, // Use this field to set up the hight position of NPC's name above his head
    random_dialog = {dialogue id, dialogue id}, // Use this table to start dialogue form a random position (ex.: {1, 3} will randomly start from 1 or 3 dialogue line)
    sequence = "name of the animation", // id for sequence animation, use table (ex.: {"id1", "id2"}) to play random animation
    dialogs = {
        [dialogue id, start from 1] = {
        ["Line"] = "Text that NPC tells you",
        ["Sound"] = "Path to sound, keep it empty or nil value if you do not want use any sfx",
        ["Answers"] = {
                {"Answer text", id for next line "close" to close the dialogue or { id, id } for random line, callback function , check function, "playback animation"},
            },
        }
    }
}

NPC position customization

To spawn your NPC on multiple maps in different locations you must add new value, for each map you need, inside the pos table. The key for the value is the map name, the value itself is a table with NPC’s position and angle. If you want to spawn the NPC on maps that are not in the list use “all” instead of the map name.

Note. If you’ll create two or more different spawn positions for one map, only one will work. You cannot spawn the same NPC more than one time on the same map.

Example:

pos = {
   ["gm_atomic"] = {Vector(570.41230,760.10539,-3123), Angle(0,90,0)}, // spawn npc on gm_atomic map
   ["rp_evocity2_v2p"] = {Vector(4213,5345,621), Angle(0,180,0)}, // spawn npc on rp_evocity2_v2p map
   ["all"] = {Vector(0,0,0), Angle(0,0,0)}, // spawn npc on all other maps
},

Skin and Bodygroup setup

To set skin, if the model you use features multiple skins, simply add skin = skin_id, the line to the NPC table, where skin_id is your skin's ID number.

For the bodygroups - add table bgr = {[1] = 2,[2] = 0,}, Table structure:

[The id of the body group you're setting. Starts from 0] = The value you're setting the body group to. Starts from 0

Tip. We recommend using Easy Bodygroup Tool for this

Example:

Let’s give the clipboard to Dr. Kleiner

 model = "models/kleiner.mdl",
  bgr = {[1] = 1},
  sequence = "lineidle03",

Random animation

To make your NPC play random animation every time it spawns, simply create a table for the sequence line.

Example:

NPC will spawn with one of these 3 animations

 sequence = {"scaredidle","lineidle02","lineidle01"},

NPC's name adjustment

To adjust the height of NPC’s name after the main setup was done, edit namepos = number, line inside the NPC table. This can be useful if you use bigger or smaller models.

Example:

NPC uses crouch animation and we slide to name a little bit down

 namepos = 30,

Random dialogue start

To start a dialogue from a random line you can add this parameter random_dialog = {number id, number id, number id},  to the NPC table, after the main setup was done. When a player starts a dialogue with the NPC, one of the dialogue line ids will be chosen randomly to start as a first line, instead of opening the first one.

This can be useful to make dialogues with frequently used NPCs less boring.

Example:

This will randomly open the first, 2nd, or 5th dialogue as a first one

 random_dialog = {1, 2, 5},

Random dialogue on the answer

To start a random dialogue on a certain answer randomly, you can create a table instead of id for the next line  {number id, number id, number id},. When the player chose this answer, one of the dialogue line ids will be chosen randomly as the next answer.

Example:

This will randomly open the 4th, 5th, 6th, or 7th dialogue as randomly as an answer

["Answers"] = {
   {"Tell me a joke!", {4, 5, 6, 7} },
},

Extra functions for the answer table:

Сallback function

Description: This function called clientside when the player chooses the answer, keep it nil to ignore it.

Example 1:

Sends a net message to the server

["Answers"] = {
   {"Show me what you got", "close", function() net.Start(“Open_some_menu”) net.SendToServer() end},
},

Example 2:

Ignores callback function while using check function

["Answers"] = {
   {"I’m fine", "close", nil ,function() return LocalPlayer():Health() >= 100 end},
},

Check function( Entity npc )

Description: Clientside function that controls whether to add the answer to the list or not. Must return boolean

Arguments: Entity from where this function was called

Example 1:

Sends a net message to the server

["Answers"] = {
   {"I’m fine", "close", nil ,function() return LocalPlayer():Health() >= 100 end},
   {"I’m injured", "close", function() net.Start(“Buy_Health”) net.SendToServer() end, function() return LocalPlayer():Health() < 100 end},
},

Template to choose job via NPC:

Change job to Civil Protection via dialogue.
Note: If you want to start the vote for changing job, add “vote” before the job command (see line 3)

["Answers"] = {
   {"I want to become a CP", "close", function() RunConsoleCommand("darkrp", "cp" ) end},
   {"I want to be a mayor", "close", function() RunConsoleCommand("darkrp", "votemayor" ) end},
},

Template - Job-resticter answers

Shows first line only to Civil Protection job and other for other jobs:

["Answers"] = {
   {"Hi officer", "close", nil, function() return LocalPlayer():Team() == TEAM_POLICE end},
   {"What do you need, bugger", "close", nil, function() return LocalPlayer():Team() ~= TEAM_POLICE end},
},