tutorial Custom Mod Console Commands

[Crystal]

Have you ever wanted to add a new admin-only console command from a mod? Well, there is a poorly documented feature for this called ScriptCommand. Basically, an admin on a server can type something like one of these:

cheat ScriptCommand dothing
cheat ScriptCommand dootherthing

This will fire an event with the string they entered (like "dothing") as part of the payload. A mod can register to hear about this event and do logic based on the string entered.

I spent over two hours the other day trying to figure out how to set this up in a mod, and finally managed to figure it out after downloading the SOTF dev kit and seeing how they did it there. To hopefully save other people from having to go through the same pain, I will show how to do it here.

1. Create a Mod

There are plenty of tutorials around on how to create a basic mod. So, I will not go into the details here. Your mod should have at the least a level asset and a game mode asset (which is referenced by the level).

2. Register for the Event

Open the event graph for your mod's game mode (edit the asset, click the graph button in the top right of the window). Then, right click in the graph, search for "onactor" and choose "Bind Event to OnActorCustomEvent" to add this node to the graph (pictures below).

Once the node is in place, drag and drop a line out to the left from the "Event" pin and choose "Add Custom Event for Dispatcher" from the window that pops up. You can name the event anything you want. You now have your event handler in place.

3. Setup the Event Processing

You will need to add some more nodes to get everything hooked up. See the picture below for what the graph should look like when you are done.

4. Do Your Thing

Once you have the graph built, you can add as many things as you want to the "Switch on String" entity. The name of each pin will be the name of the command that a person can enter using ScriptCommand in game. So, just hook up your custom command logic for each one!

Pictures

[Crystal]

By the way, the "Instigating Actor" pin on the event handler will be the player that ran the command. So, if you want to do anything specifically with that player (like give them items or something), you can cast that pin to a PlayerControllerBlueprint and make use of it however you need.

Here is an example where I made a mod with special versions of metal irrigation pipes for admins only (they are always irrigated and can be placed infinite times). Running the command "cheat ScriptCommand GetPipes" will give the admin a copy of each type of pipe.

[Crystal]

It seems I can only get this to work for the first mod in the load order. I tried a lot of different ways to get it to work as the second mod and got nowhere. It seems the only thing that gets loaded for mods after the first is the primal game data, and the graph for that has no entry points. If anyone knows of a workaround to get a game mode to load when it is not the first mod, please let me know.

[Qowyn]

Instead of adding your code to GameMode you should create a Map Extension and use the Begin Event of the Level Blueprint to add that event. This way it will be stackable with everything (except total conversions). And thanks for making the tutorial, there is just one thing you didn't mention yet: ScriptCommand works for RCON too, allowing modders to add things that can be triggered by external programs. You just need to lowercase the command right before the switch because programs like ARKon send everything lowercase and "Ignore Case" in the switch thing is broken in ARK.

[Crystal]

16 hours ago, Qowyn said:

Instead of adding your code to GameMode you should create a Map Extension and use the Begin Event of the Level Blueprint to add that event.

I tried that, but the level did not load (or at least it did not appear to, no graphs executed). I probably just did it incorrectly. Is there some information somewhere on how to make a proper map extension that is always loaded on any map?

Thanks for the RCON tip! I also recently discovered that ignore case is broken. I have just been making all commands lower case only, but I did not think about lower casing it in the graph to allow people to enter it in any case.

[Qowyn]

Quick Tutorial: Create a new level in TheIslandSubMaps and either place a "Controller Structure" or add a graph to the Level blueprint with your logic in it. That level must not have a reference to PrimalGameData. For Cooking just specify the name of the map extension level first, then your regular cooking map, seperated by comma and cook as Map Extension. Your cooking map should still include Primal Game Data. Should work everywhere.

[WoefulMacabre]

Or you can bypass a map extension and/or unstackable mod entirely by just binding to that dispatcher from outside of the GameMode...

-WM

EDIT: @Jat @Jen Whoever's in charge of media/the forum really needs to re-evaluate their link filtering decisions... every time I try to edit in the attached screenshot from Gyazo using "Insert Other Media > Image from URL, it gets stripped out... not really acceptable. If an image is going to get stripped out due to some stupid URL filter/whitelist/blacklist nonsense, perhaps trigger an error like when trying to use this image preview URL in place of this direct URL.

[Crystal]

2 hours ago, WoefulMacabre said:

Or you can bypass a map extension and/or unstackable mod entirely by just binding to that dispatcher from outside of the GameMode...

This looks great. However, I cannot find how to add the "Server Event Binding" event. Where does that come from? Also, in which blueprint do you recommend adding the graph if not the level or the game mode?

[WoefulMacabre]

Doesn't really matter which event graph you put it in. That graph just happens to be within ACM's central processing actor which is hidden in the world. It just needs to be within a graph that is executed at some point in the world so that the command(s) will be valid in the console.

And that is a Custom Event of my own making told to run on the server.

-WM