As an overview, to make an Addon for NPC Companion, you'll need a Pack Script to define all the included NPCs. As well, for each NPC in your addon, you will need:

• An entry for the NPC in the Pack Script, with appropriate settings.
  
• Puppet Parameters (ep) and Behavior (cb) as per any puppet, with some specifics.
  
• A 512x512 Preview Image of the NPC (preferably with a transparent background).
  
• A template holder file for the Puppet Spawner, which will use the Parameters and Behavior.
  
• A template holder file for the Menu Button, which will use the Preview Image.

To help with creating your Addon, I've included a level to help with the creation and testing of NPCs, which you can find at:
Content/Shared/Levels/NPCCompanion/NPCCompanion_CreationAndTesting.wld

For creation, I've layed out my SS2Natives NPCs for reference, as well as a much simpler set of Template NPCs that you can use as a base. The Pack Script for each pack is above the relevant NPCs (on the SSHD side), and in front of each NPC is a script entity that holds the NPC's Template Holders (for spawning the button and puppet) linked in the Variables of the Script entity itself. Additionally, there's a section outside the testing area for creating NPC Thumbnails. More details will be given in this guide.

For testing, there's a script placed on the map (between the creation areas) that enables testing in Singleplayer and Deathmatch (since custom gamemodes don't work in the editor). Note that the bind to toggle the menu is changed to Sprint, since Netricsa is enabled for Singleplayer. If you want to test your NPCs on a different map, copy that script entity to the desired map; Just don't accidentally leave it saved in a map you're working on or anything. Also yeah, there's some testing areas available for moving around, swimming, and fighting. If you ever need to rebake Navigation cause you added some obstacles, note that the SS3 buildings will only bake correctly in the SS3 gtitle due to the player size.

Please be sure that any NPC Addons you release do not override the test level or any part of another Addon Pack, especially the Template pack.


To note, these kinds of Companions currently aren't supported:

• Melee-only Companions that try to get near the enemy to do a melee attack (like those under Attacks>Melee). Like, you can do it, but due to the nature of how behavior areas work, puppets do not consider the width of enemy puppets, so large puppets like Red Biomechs and Khnums would trample the Companion before the Companion even considers doing a melee attack. You can possibly get away with Companions that ram or lunge at the enemy, or explode like Kamikazes.
  
• Very Large Companions. Again, you can still do it, but currently the spawning/teleporting area checks can't be adjusted.
  
• Ridable Companions that can also fight by themselves when not being ridden.

Flying, Turret, and Vehicle Companions are possible, but currently untested. Vehicle Companions will not be usable in multiplayer, as vehicles don't sync correctly for clients. Also, currently, the most the script does for vehicles is setting EnableUsage on the puppet, so you would still have to do your own scripting for mounting and such.


Also, as a general editor tip, if you want to resave a resource without all other instances of that resource in the level being switched over to the resaved one, `Unshare` the resource before resaving it.


So now that that's all out of the way, let's get down to the details.

Firstly, you'll want to come up with an internal name for your pack, as this will be used for important file and folder naming. For example, my "Serious Sam 2 Natives" pack has the internal name "SS2Natives". The internal name should be something relatively short and unique. You can change the display name whenever, but changing the internal name could be troublesome if you do it partway through making your pack.

By the end, these will be required:

• Content/SeriousSamFusion/Scripts/Startup/NPCPack_[PackName].lua
  
• Content/Shared/Presets/Templates/NPCCompanion/[PackName]/

This is only required if you set up tools in the pack script:

• Content/Shared/Databases/Tools/NPCCompanion/[PackName]/

And these aren't required, but are suggested locations for relevant files:

• Content/Shared/Models/NPCCompanion/Packs/[PackName]/
  
• Content/Shared/Textures/Interface/NPCCompanion/Packs/[PackName]/
  
• Content/Shared/Databases/Puppets/NPCCompanion/[PackName]/
  
• Content/Shared/Databases/Behaviors/NPCCompanion/[PackName]/
  
• Content/Shared/Databases/Projectiles/NPCCompanion/[PackName]/

The pack script is very important, as it defines all of the NPCs in your pack. The script for your pack is to be located in `Content/SeriousSamFusion/Scripts/Startup/`, and be named `NPCPack_[PackName].lua`, with "[PackName]" being replaced by the internal name of your pack. If the internal name doesn't match the filename, the script will fail to load ingame.

It's suggested to use the Template pack script as a base, but for the sake of the guide, here's a much more simplified example:


Upon first saving the script to the proper place, it won't be ran until you either restart the editor, or enter `dofile("Content/SeriousSamFusion/Scripts/Startup/NPCPack_[PackName].lua")` into the console. You'll only need to do this once.

Most of what's in the example I hope is self-explanatory by this point. The chunk at the end is required for the script to work; Don't mess with it unless you know what you're doing.


Now, as for what parameters there are for each Companion:

Most of these affect NPC availability, and information shown when hovering over the NPC in the selection menu.

Author = "String",
Overrides the AuthorName used for this NPC, in the case of multiple authors working on a pack.

Origin = "String",
Optional. Lets you indicate where the NPC comes from, whether it be a game, series, or whatever.

ExcludeSSHD = true/false,
The NPC will not be selectable in TFE HD and TSE HD style gametitles.

ExcludeBFE = true/false,
The NPC will not be selectable in the Serious Sam 3 style gametitle.

SinglePlayerOnly = true/false,
The NPC will only be selectable in the Singleplayer gamemodes.

IsVehicle = true/false,
Experimental. NPC is treated as a ridable vehicle. Automatically sets `SinglePlayerOnly`, `DisableCombat`, `DisableFollow`, and `DisableAutoJump`.

IsTurret = true/false,
Experimental. NPC is treated as a stationary turret. Automatically sets `Unmoving`, `DisableFollow`, and `DisableAutoJump`. Can be combined with `IsVehicle`.

SlotsRequired = #,
The number of slots this NPC takes up. Default of 1, max of 4.

IsUniqueChar = true/false,
Places additional restrictions on using multiple of this NPC. When in Singleplayer, or `Unique NPCs` is set to Unrestricted in Multiplayer, each player can only have 1 of this NPC. With Restricted set in Multiplayer, only 1 player can use this NPC at a time (but the player can only have 1 Unique NPC overall).

OnePerPlayer = true/false,
Untested. Similar to above, but without being affected by the Restricted setting.

IsFlyingChar = true/false,
The puppet flies, which my script needs to know for handling movement overrides.

SpawnHeightOffset = #
A Y-coordinate offset for how far above the ground the puppet should spawn. Useful for flying puppets, and puppets centered on 0,0,0.

UseFoeAssignedSound = true/false,
If this is set, the NPC will use the `NPC_FoeAssigned` sound scheme when it finds a new foe.

UseSpawnEffectAttachment = true/false,
If this is set, you can set up a `NPC_SpawnEffect` attachment to determine where the effect for spawning and teleporting is aligned to. Useful for puppets that are centered on 0,0,0.

RegenPerSecond = #,
How much HP the NPC will regen per second when out of combat. Defaults to 5.

SpawnEffectsName = "String",
This allows you to override the default spawn/teleport effects with your own. Whatever name you put in for this, it'll try to find a valid template at:
`Content/Shared/Presets/Templates/NPCCompanion/Template_SpawnEffects_[SpawnEffectsName].rsc`.

DisableCombat = true/false,
If set, the NPC will not fight with enemies, nor will enemies target it. This is automatically set if AggroRange is not set, or is 0 or below.

DisableAutoMove = true/false,
If set, NPC will be unable to use automatic movement, such as projectile dodging and movement overrides (like `Away` and `Circle`). Automatically set if `ClimbHeight`, `StepHeight`, or `DropHeight` aren't set, and implicitly set if `Unmoving` is set.

DisableDodging = true/false,
If set, NPC won't try to dodge incoming projectiles. Implicitly set if `DisableAutoMove` or `Unmoving` are set.

DisableAutoJump = true/false,
If set, the NPC will not try to jump up ledges. Automatically set if `PuppetWidth`, `ClimbHeight`, or `StepHeight` aren't set, and implicitly set if `Unmoving` is set.

DisableFollow = true/false,
If set, NPC will not follow the player, defaulting to "Hold" movement. Implicitly set if `Unmoving` is set.

Unmoving = true/false,
If set, NPC will be unable to move. Automatically set if `IsTurret` is set.

AggroRange = #,
The range that the NPC will search for enemies. This should match up with the `Active Range` set in the Behavior. If this isn't set, `DisableCombat` will be set automatically.

AttackDescriptions = {Table},
Should contain a table of strings describing what kind of attacks the NPC uses in general. For example:

Parameters more specifically for fighting, which can also be used with `FightModes`.

FightMovement = {MultiTable},
This is a table containing additional tables, defining the NPC's speed at different distances, and allows you to set Move Overrides like `Away` and `Circle`. For example:

AttackPreferTargetHealthRange = {#,#},
When searching for enemies, the NPC will have a preference for enemies with health between the two given numbers.

AttackTraceWidth = #,
The amount of clearance to try and ensure any attacks have when choosing where to move. Probably shouldn't be set higher than 1.

AttackSplashSearchRadius = #,
AttackSplashSearchHealth = #,
When searching for enemies, increases priority for enemies that are bunched up.

AttackProjectilePiercing = #,
AttackProjectileSpeed = #,
AttackProjectileLifetime = #,
When searching for enemies, increases priority for enemies that are guaranteed to be pierced and have another enemy behind them.

ToolRight = "String",
ToolLeft = "String",
Allows you to define tools that will come up while the NPC is in combat. The Tool parameters must be located in `Content/Shared/Databases/Tools/NPCCompanion/[PackName]/`, and all you need to enter is the filename of the tool without an extension, like so:
If you want your NPC to always be holding a particular tool, you don't need to set this; Just add the tool in the puppet's EP.

FightModes = {MultiTable},
Allows you to define up to 4 Fight Modes, each of which can have their own Behavior state defined. For example:
In fact, all of the previous parameters listed under `Fight Parameters` are also usable in the individual Fight Modes!

Most of these are values from the puppet that the script otherwise does not have access to.

CanSwim = true/false,
Set this if the NPC has the `Diving` movement ability.

ShootTargetHeightOffset = #,
Body > Others shoot at me > y, multiplied by Stretch.
ShootTargetHeightOffset_Swim = #,
Legged body > View height (swim), multiplied by Stretch.
If both of these are set, and the swim one is lower, the script will use these values to detect if the NPC is swimming (if CanSwim is set). Otherwise, the script will go off of the shape of the collision hull, where a tall hull is detected as standing, and a round hull is detected as swimming.

PuppetWidth = #,
The width of the puppet when standing normally, accounting for stretch.

PuppetWidth_Swim = #,
The width of the puppet when swimming, accounting for stretch.

ViewHeightOffset = #,
Body > I am looking from > y, multiplied by Stretch.

ShootHeightOffset = #,
Body > I am shooting from > v > y, multiplied by Stretch.

SizeScalesByGtitle = true/false,
If set, automatically scales down the above parameters when playing on SS3-style maps. Note that this does not scale down the NPC's puppet and such for Serious Sam 3 automatically; You still have to manually set that up.

NormalMoveSpeed = #,
NormalMoveSpeed_BFE = #,
Land > Max speed. This value should match the player's speed for the Gtitle, for following.

StepHeight = #,
StepHeight_BFE = #,
Height at which puppet will not auto-jump, and just step up steps.

ClimbHeight = #,
ClimbHeight_BFE = #,
Maximum height for ledges that the puppet will auto-jump up on.

DropHeight = #,
DropHeight_BFE = #,
Legged body > Navigation fall/step down height.

If you have multiple NPCs that have similar parameters, there are some scripting tricks you can do to cut down on redundant information. This is entirely optional, but it makes doing edits easier.

For any parameters that use tables (the ones in curly braces), you can instead put the table in a separate variable, and apply that variable in the appropriate places. So instead of:
You can do:
You can also do this for standalone numbers and strings, but it doesn't save nearly as much space.

If all of your NPCs share certain parameters, there's another thing you can do to apply the same value to all of them. Between the last Companion and the "boilerplate" code at the end, you can insert something like this:
You can also adjust the `for` statement to have it only apply the parameters to Companions within a certain range. So say if you only wanted it to apply to Companions 3 through 8, you'd go:
Just be sure that if you do make changes to the order and/or number of Companions, that you keep the numbers here up-to-date.

Gonna be real: I'm not going to explain how to create an NPC puppet and behavior in full. But, there are some specific things you should follow when creating your puppets for this. For a lot of things, you can take from the Template NPCs.

• BFE versions are not automatically done. In order to have appropriate size and movement parameters, you will have to provide BFE-specific versions of the NPCs. For reference, the BFE stretch is `0.88785032`.
  
• I recommend if your NPC uses projectiles based off of what enemies use, that you recolor the projectile so that it can be identified as not from an enemy.
  
• Similar recommendation for if the NPC themselves is based off of an existing Serious Sam enemy. While there is a marker above NPCs, at least try and make the NPC visually distinct from the enemy, such as by giving it a different color scheme.

• `Character Class` should be "Companion", otherwise clients won't be able to find their own NPCs.
  
• Under `Moving abilities`, should have `Same velocity on all difficulties` set.
  
• For every projectile's Expected Damage Inflictor, you should have "Shared Alignment" set, as the NPC's alignment flips between Good and Semi-Neutral.
  
• In order to be able to pass through NPCs (a necessity for some BFE levels), you need to set `Is kicker` and `Allow trampling` in the Kicking params. If you don't want your NPC to deal Kicking damage to enemies, set `Velocity ratio to kick` to 100, `Applied damage` to 0, etc.
  
• While movement capabilities can definitely vary depending on what kind of NPC you're making, it is highly recommended that your NPC can keep up with the player when following. This means that the NPC should have 10 `Land>Max speed` in SSHD, and 8.5 `Land>Max speed` in BFE, and if the NPC can swim, 7.5 `Water>Max speed` in both game types. If you want the NPC to move at a different speed in combat, use a `FightMovement` table for the NPC in the pack script. While you can set speed multipliers in the Behavior, that isn't recommended, since it won't play the correct speed animations for clients.

• If not otherwise defined, the puppet will use the "Default" state when fighting enemies.
  
• If the NPC is set to follow the player, it requires a "FollowPlayer" state set up similarly to my NPCs.
  
• DO NOT use `Away from foe` or `Circle around foe` movement types, as those are prone to crashing the game in certain areas. I have custom replacements for those that have to be set up in the pack script via `FightMovement`.

• You need to have an "NPC_Marker" attachment, to determine where the marker above the NPC should be placed. If the NPC can swim, you also need an "NPC_Marker_Swim" attachment.
  
• If you want the NPC to play a sound when encountering an enemy, don't use "Sight", as that'll also play when targetting the player to follow them. Instead, use a scheme sound called "NPC_FoeAssigned", and set `UseFoeAssignedSound` for the NPC in the Pack Script.

This is going to cover the way I do the transparent background for my thumbnails. This will require:

• An image editing program; I'll be using GIMP.
  
• A somewhat modern screen resolution, enough to be where you can make the editor viewport at least 512x512.

Note that this does not work for NPC models that have transparent parts against the background. Maybe you can work out something by taking multiple images with and without solid versions of the transparent parts, but I don't know. The alternative is doing a render in Blender, but lighting will probably be noticeably different.

Anyways, outside the main part of the level, you can find this setup:
I have all of the setups I used for the SS2Natives and Template packs here for reference, as well as some empty models you can put your NPC models on. You don't need to keep the reference ones around if you don't need them, especially since all of the spotlights are dynamic, and may slow down older PCs. If you ever need more model spots, you can select a set of entities (model, camera, spotlight) and use the Clone tool (Misc > Clone).

Firstly, put your NPC model on a model spot, and choose an animation to play via `Auto start animation`. If it's not a pose animation (like I've been using `Idle01` for mine), I would suggest never pressing the play button in the world editor, just so you have a consistent pose for camera positioning. Select the camera entity, press Numpad 6 for ingame view, press Y to go into entity view, use Esc to move around like you would normally with the editor camera, and position the camera however you want for the NPC. It should look something like this:
If the Tool name in the top-right is covering part of the model, you can increase the `Default aspect` on the camera entity until it's off to the side enough that it won't be in the square:
Now, use the PrintScreen key on your keyboard to take a picture of the entire screen, open up GIMP, and paste the screenshot into GIMP.
We have one more to do, so back in the editor, get out of entity view with Y, select the white background plane, hide it with `Visibility > HideSelected`, Numpad 9, select the camera again, Y, Numpad 6. This should be where you're at now:
PrintScreen, paste the screenshot into GIMP, and put it on a new layer.

Now in GIMP, you should crop the image to be a square in the viewport. Using the selection tool to select the whole inside of the viewport, `Image > Fit Canvas to Selection`, and then use `Image > Canvas Size...` to make the make the canvas a square. You should end up with something like this:
Reorder the layers so the black background is on the bottom, select the white layer, and set the mode to `Color erase`:
If you still have the Tool name text in the top-right, you can select and delete it now from the black layer. Next, do `Layer > New from Visible`, hide the white layer, and set the "Visible" layer's Mode to `Color erase`:
Almost there. Do `New from Visible` again, hide all the layers except the new "Visible" layer, and do `Image > Scale Image...` to scale it down to 512x512:
From here you can export this to:
Content/Shared/Textures/Interface/NPCCompanion/Packs/[PackName]/[NPCName].tga
And import it into SEd as you would normally.

If you want to make another, you can Ctrl+Z to before you resized, select either the black or white layer, and paste in any further screenshots, which should line up with your canvas (assuming you didn't move the SEd window). In SEd, you can unhide the white background plane by doing `Visibility > Show hidden`.

Now that we have a puppet and associated image, we need to set up Template Holders so that the script can actually spawn them ingame. For each NPC, you will need the following Template Holders:

Content/Shared/Presets/Templates/NPCCompanion/[PackName]/Template_Button_[NPCName].rsc
Content/Shared/Presets/Templates/NPCCompanion/[PackName]/Template_Spawner_[NPCName].rsc

Additionally, when playing Serious Sam 3, these will be automatically loaded instead if they exist:

Content/Shared/Presets/Templates/NPCCompanion/[PackName]/BFE/Template_Button_[NPCName].rsc
Content/Shared/Presets/Templates/NPCCompanion/[PackName]/BFE/Template_Spawner_[NPCName].rsc

To help with finding and editing these Template Holders, I have them linked in a Script entity in front of each NPC in the test level:

You can resave the ones from the Template pack, and use them as a base for your NPCs.

For the Button Template Holder, you don't want to change the model. Instead what you want to do is go into the `Shader modifiers`, and change the linked texture to the one for your NPC:
Technically you can make an edited version of the button model (if you wanted to change how elements are styled), but I don't recommend it in case I add or change elements of the button.

For the Puppet Template Holder, it should be pretty simple; Just put in the EP and CB files from your NPC:
You can also adjust any of the Puppet Entity Properties as you see fit, just be sure you don't change the Spawner stuff.


Beyond that, you can edit the Name of the Button and Puppet entities in the Template Holders to match your Pack and NPC. It's not necessary currently, but I will judge you. The names are formatted like so:

Button: NPCInterface_NPCSelect_[PackName]_[NPCName]
Puppet: Spawner_Companion_[PackName]_[NPCName]

To help with packing your Addon Pack, you can use AutoGro 2018[github.com] to pack a level that has all your NPC assets in it. You can use the test level for this if you've been working there, but be sure you go through the resulting GRO and delete the level and any other files unrelated to your NPCs that you may've accidentally saved. You can also copy all your NPCs and related scripts to an empty level and use that to pack. Be sure all of the Tools and Template Holders are referenced in the level, and when doing updates after-the-fact, note that AutoGro won't pick up any files in the folder that are behind a file in a GRO, so always good to go through the packed GRO to make sure everything's there.


For your release on the workshop, I would like if you were to include this in the thumbnail on the workshop, as to indicate that it is an addon for NPC Companion:
It doesn't have to be in that corner exactly, but just to give a general size.