Custom Terminal Command

Terminal commands are UObject classes derived from UOperatingSystemTerminalCommand. The bundled Terminal program discovers them as primary assets and executes them when the player types the matching command.

sequenceDiagram
  participant User
  participant Term as UOperatingSystemTerminal
  participant Cmd as UOperatingSystemTerminalCommand
  User->>Term: Type MainCommand + arguments
  Term->>Cmd: ProcessCommand(TestCommand)
  Cmd->>Cmd: OnProcessCommand / K2_ProcessCommand
  Cmd->>Term: AppendOutput to ParentTerminal
  Cmd->>Term: ContinueExecution

Blueprint command

1. Create the command asset

1. Content Browser → Add → Blueprint Class
2. Search Operating System Terminal Command and pick the base class.
3. Name it BP_CMD_Hello (name is arbitrary; Main Command property is what the player types).

2. Configure properties

Property	Example	Notes
Main Command	hello	What the user types (no slash prefix)
Description	Greets the user	Shown in help output
Alternate Commands	hi, greet	Optional aliases
Supported Operating Systems	Leave empty	Empty = all OS types
Command Flags	-v with description	Optional; prefix with - or --

3. Implement Process Command

Override the On Process Command event. Use Get Command Parameters to read arguments after the command name.

The bundled BP_CMD_Help uses this exact graph shape:

flowchart LR
  E["Event: On Process Command"] --> L["Your logic function<br/><i>e.g. display help text</i>"]
  L --> F["Finish Command"]

Example logic:

Event On Process Command
  → Append String to Parent Terminal Output ("Hello from custom command!")
  → Finish Command (Error If Any: empty)

Finish Command (or Continue Execution) must be called when finished — it tells the terminal the command completed. Study Shared/Blueprints/TerminalCommands/BP_CMD_Help in plugin content.

4. Register with Terminal

Assign your command class on the Terminal program Blueprint (or add it to a command collection Data Asset used by your OS). Bundled examples live under:

OperatingSystemContent/Shared/Blueprints/Programs/Terminal/Commands/

Duplicate those assets into your project folder — do not edit plugin originals.

5. Test

Boot your OS, open Terminal, type hello (or your Main Command).

C++ command

Header

#pragma once

#include "Programs/Terminal/OperatingSystemTerminalCommand.h"
#include "CMD_Hello.generated.h"

UCLASS()
class UCMD_Hello : public UOperatingSystemTerminalCommand
{
    GENERATED_BODY()

protected:
    virtual void OnProcessCommand() override;
};

Source

#include "CMD_Hello.h"
#include "Programs/Terminal/OperatingSystemTerminal.h"

void UCMD_Hello::OnProcessCommand()
{
    if (UOperatingSystemTerminal* Terminal = ParentTerminal.Get())
    {
        Terminal->AppendOutput(TEXT("Hello from C++!"));
    }
    ContinueExecution();
}

Set Main Command in the class defaults (or a Blueprint child of your C++ class).

Build.cs

PrivateDependencyModuleNames.AddRange(new string[] { "OperatingSystemSimulator" });

Root-only commands (Unix)

On UOperatingSystemUnix, enable Requires Root Permission and implement Process Command As Root (Blueprint) or OnProcessCommandAsRoot() (C++). The player must prefix with the OS root command (e.g. sudo hello).

Bridge to gameplay

Commands often broadcast gameplay events through Global Messenger. The standalone demo game opens a roof door this way — no direct reference between Terminal and level actors.

API reference

• UOperatingSystemTerminalCommand
• UOperatingSystemTerminal
• FOperatingSystemCommandFlag — flag struct on the command page