S&box Wiki

Creating a runtime addon

Creating an addon project

Start s&box in "Content Mode".


Once in game, select "New Project..." under "File" on the menu bar.


Select the "Addon" project type and give it a name.


Coding your runtime addon

Once created, right-click your addon under the "Addon" list in the "Projects" dock and select "Open in Visual Studio". See: Setting up Visual Studio for a guide on setting up VS.


Right click your project and create a new class with Add->New Item... (or press CTRL+SHIFT+A), and then give your new class a name.


The file you just created is where you'll be creating the "Primary Type" class for your runtime addon. In the case of the Sandbox gamemode, this is the entity that users of your addon will spawn when they select it in the entities list. You'll need a class which inherits from some kind of Entity. You'll most likely want to use ModelEntity.

The code for the runtime addon featured in this article is very basic:

namespace Sandbox; public partial class MyAddonThing : ModelEntity { private TimeSince _lastJump; public override void Spawn() { base.Spawn(); Model = Cloud.Model( "facepunch.soda_can" ); SetupPhysicsFromModel( PhysicsMotionType.Dynamic ); } [GameEvent.Tick.Server] private void OnTickServer() { if ( _lastJump >= 3 ) { PhysicsGroup?.AddVelocity( Vector3.Up * Game.Random.Next( 80, 120 ) + Rotation.Forward * 60 ); _lastJump = 0; } } }

This code defines a soda can entity that'll hop forwards every 3 seconds.

Preparing to upload your addon to asset.party

Once you are ready to upload your addon to asset party click the cog on your addon in the "Projects" dock. (Or right-click it and select "Project Settings...".)


Assigning your addon to your organisation and tags

Once here, make sure to set "Organisation Ident" to that of your asset.party organisation. Make sure to add the tags "entity" and "runtime" to the "Tags" of your addon.

These tags are required for your entity to show up in the entity list in the Sandbox gamemode and be eligible to spawn. These requirements may change in the future, especially if/when the Sandbox gamemode is re-written.

If you're creating an NPC, include the tag "npc".

Target Game

As this guide assumes you are making addons for the "Sandbox" gamemode, you'll need to set "Target Game" to "facepunch.sandbox". For other gamemodes, it's as simple as: orgident.gamemodeident.


Primary Type

Find "Runtime Addon" under "Addon".


Set "Primary Type" to the class you made earlier. The way you do this is by typing the full class path, including namespaces.

In our case, it's Sandbox.MyAddonThing.


If your class were under a different namespace, such as Sandbox.Entities.Fun, then you would include it in full: Sandbox.Entities.Fun.MyAddonThing.

The reason you need to set Primary Type is so that the target gamemode knows which class to instantiate when you want to create/spawn your addon in-game. For example, the Sandbox gamemode does something like this:

var entityname = package.GetMeta( "PrimaryAsset", "" ); await package.MountAsync( true ); var type = TypeLibrary.GetType( entityname ); var ent = type.Create<Entity>(); // Do stuff with "ent"

See: Mounting assets at runtime for more information about mounting packages at runtime.

Uploading to asset.party

Under "Publishing", click "Upload To Asset Party".


Select your org like before, click "Next" and follow the upload wizard's steps.

Addon Publish State

After your addon is done uploading, click the "View on asset.party" button on your addon in the "Projects" dock.


Set the "Publish State" to Released, otherwise your addon will not appear in-game. After that's done, click "Save Changes". Your addon is now ready to be used in the Sandbox gamemode.

It may occur that the asset.party version of your addon no longer has the tags you applied earlier. You may have to re-apply them on the website.