Creating your first Cathode script

CathodeLib makes it easy to develop custom scripts for Alien: Isolation in C#, by allowing simple access to the game's internal "Cathode scripting system".

Making your first script is easy!

1. Include CathodeLib in your project:

   • Create a new C# .NET Framework project in Visual Studio
   • Right click on the project and select "Manage NuGet Packages"
   • Click "Browse" and search for "CathodeLib", then click "Install"
   • Navigate to your CS file, and at the top, add using CATHODE.Scripting

2. Create your Commands file:

   • Commands commands = new Commands("COMMANDS.PAK");

3. Create your first script (called a Composite):

   • Composite composite = commands.AddComposite("My Cool Script", true);
     • The first parameter names the script "My Cool Script".
     • The second parameter sets this script as the one we'll run first when we load our level.

4. You can now add entities to your composite to perform logic in-game:

   • For this example, we'll show an objective when the level starts up - so let's add some Function entities to our composite:
     • FunctionEntity checkpoint = composite.AddFunction(FunctionType.Checkpoint);
       • The Checkpoint Function entity will allow us to trigger other entities when it itself is triggered.
     • FunctionEntity objective = composite.AddFunction(FunctionType.SetPrimaryObjective);
       • The SetPrimaryObjective function will show an objective when triggered.

5. With your entities added, you can now give them parameters to customise them:

   • Continuing with the objective example, let's add parameters to our Checkpoint Function entity:
     • checkpoint.AddParameter("is_first_checkpoint", new cBool(true));
       • The parameter is_first_checkpoint tells the game that our Checkpoint should be triggered when the level starts up.
       • The datatype of the parameter is boolean, which we define as a cBool - various other types are available, such as cString, which we'll use next!
     • checkpoint.AddParameter("section", new cString("Entry"));
       • The parameter section gives our Checkpoint a name - in this case, we're calling it "Entry".
   • Now, let's customise our objective by giving our SetPrimaryObjective Function some parameters:
     • objective.AddParameter("title", new cString("Do Something!"));
       • Here we're giving our objective a title - this can be a regular string, or a localisation ID.
     • objective.AddParameter("additional_info", new cString("Hey, you should go and do something!"));
       • Now, we give our objective a description, which players can view when they open the TAB menu.

6. Add links between the entities:

   • Entities can be linked via their parameters, just like how nodes are linked within Blueprint in Unreal Engine. This allows entities to share data, or simply just trigger eachother when events occur. For our example here, we'll trigger our objective when our Checkpoint has loaded.
     • checkpoint.AddParameterLink("finished_loading", objective, "trigger");
       • finished_loading is the parameter our Checkpoint entity activates when it has loaded, and trigger is the parameter on our SetPrimaryObjective entity which causes it to activate, setting our objective and displaying the popup in-game.

7. Save your Commands file:

   • commands.Save();

That's it! If you copy your Commands file into a level's "WORLD" folder, you should now have your objective popup when the level loads.

Lets see our script in its entirety:

//Create our Commands file to contain our scripts
Commands commands = new Commands(commandsPath);

//Create our first script (a "Composite") and give it a name
Composite composite = commands.AddComposite(@"My Cool Script", true);

//Add a "Checkpoint" function to our script
FunctionEntity checkpoint = composite.AddFunction(FunctionType.Checkpoint);

//Let the game know we want to load in to our checkpoint
checkpoint.AddParameter("is_first_checkpoint", new cBool(true));

//Give our checkpoint a name
checkpoint.AddParameter("section", new cString("Entry"));

//Add a "SetPrimaryObjective" function to our script
FunctionEntity objective = composite.AddFunction(FunctionType.SetPrimaryObjective);

//Give our objective a title (visible in the initial popup, and tab menu)
objective.AddParameter("title", new cString("Do Something!"));

//Give our objective a description (visible in the tab menu)
objective.AddParameter("additional_info", new cString("Hey, you should go and do something!"));

//Trigger our objective when our checkpoint has finished loading
checkpoint.AddParameterLink("finished_loading", objective, "trigger");

//Save the Commands file
commands.Save();

---

For easy testing going forward, you can use OpenCAGE's "Launch Game" functionality, which allows you to load directly into a level, with support for custom levels outside of the ones that ship with the game.

You can also check out the OpenCAGE Wiki to view a list of entities and their parameters. Or an alternative, WIP list, here. EntityMethodInterface (which is the base class for all entities) is documented here, which provides a more complete parameter list.