MAC's NPCs v1.2 Documentation (ENG)

Basic Setup

1. To install this addon to your server just unzip it to your garrysmod/addons folder

2. Inside “mc_simple_npcs/lua/mcs_npcs” open sh_config.lua and configure the addon 

Config:

MCS.Config.UseDelay = 2			// Delay between player can press "Use" button on NPCs
MCS.Config.TextSpeed = 3			// Speed of text typing animation (1 - fastest, 10 - slowest)
MCS.Config.DebugMode = false             // DebugMode enables close button at top right corner
MCS.Config.NPCTextColor = Color(255,255,255)		// Color of NPC's text
MCS.Config.TextColor = Color(255,255,255)		// Color of answers NPC's name and skip button
MCS.Config.HighlightColor = Color(217,170,0)		// Color of answer button when highlighted
MCS.Config.LinesColor = Color(155,155,155)		// UI's outline color
MCS.Config.HLLinesColor = Color(255,255,255)		// UI's corner lines color
MCS.Config.EnableBlur = true				// Enable UI blur effect
				
MCS.Config.SkipButton = "Press LMB to skip"	// Text of skip button
MCS.Config.AnswersFont = "MCS_Arial32"		// Answer lines font
MCS.Config.NPCFont = "MCS_Arial24"		// NPC's text font
MCS.Config.AnswersAlign = TEXT_ALIGN_LEFT	// Answer text align - TEXT_ALIGN_LEFT TEXT_ALIGN_RIGHT TEXT_ALIGN_CENTER

3. 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

This menu will feature some things like autosave on close and autoload last edited NPC and a menu bar with options to load and save current NPC as a template

You also can start a fresh setup by choosing New option

NPC Setup

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

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

NPC Name position

This slider will 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, 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 preview the model on the side panel, rotate it, and zoom by double clicking it. If your model supports bodygroups or skins you will see the sliders for adjustment.

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

By pressing Get Anim. 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

To add spawn position for each map you want click Add Map button

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

Inside the text box, you can enter or modify the map name. If you want to spawn the NPC on maps that are not in the list use “all” instead of the map name.

To edit the spawn position press the Edit button:

In the opened menu, you can type spawn vector and angle or press the Player Pos button to copy your own position and the Ent Pos button to get the position of the entity you are looking at. For the manual corrections later see Advanced setup

The Dialogue setup

For a new dialogue line press the “Add Line” button. This will add a new panel to the list below.

Each line will have its own ID displayed in the top left corner. 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” button. To remove the answer press the “Del” 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 close 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 open the menu 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 Del. button. To quickly browse all available animations for the model press Get. Anim. button, which will open a list of all animations.

Note: The checkbox for use limitation must be checked on (see step 4.4 ).

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

You can quickly test the dialog by pressing the “Test the dialogs” button. Helpful for big and complicated dialogues

Saving NPC

To save the NPC press the “Copy to Clipboard and Close” button at the bottom

or choosing the “Copy Lua code” option from the Edit menu on the menu bar.

Then open sh_npcspawn.lua inside “MC Simple NPCs/lua/mcs_npcs” and paste NPC’s code to the files bottom.

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 typing the mcs_npcrespawn command in the console.

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
    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},
},