Modding guide

How to run global logic: singletons, and settings your mod reads from the ini

10 min readASA DevKit as of November 2026 (UE 5.8.1); ASE where noted

Some logic belongs to no creature or structure: a server-wide timer, a gift for every player who joins, a reaction to every death. That logic lives in a singleton, one actor the server spawns once per world. This page builds one and has it read the settings server owners put in their ini. The first takes me about half an hour; replication and restart tests take an afternoon.

  • You'll make: a singleton that starts with the server, reacts to players, and reads your mod's ini settings
  • Time: about half an hour for the first one; an afternoon with replication and testing
  • Level: intermediate (you've registered content before)
  • You'll need: a mod set up and registered, and a local dedicated server for the last test

What a singleton is

A singleton is a Blueprint actor listed in your Mod Data Asset. When the world loads, the server spawns one of it. Nothing is attached to it, so it lives until the server stops. Modders also call it a CCA, a central controlling actor; it's the same thing.

Its parent must be SaveGameActor. The list only accepts that class and its children, and it has done so since the move to ASA. A SaveGameActor is written into the world save, so variables you mark SaveGame keep their values over a restart. How to save your mod's data covers that.

The game makes sure only one of each class spawns, so you don't need your own check. Vanilla uses the same base for its boss arena managers and its persistent world data.

The process

  1. Make a child of SaveGameActor. Use SaveGameActorTickable only if you need Event Tick.

    Show me how
    • Content Browser → right-click → Blueprint Class → search SaveGameActor → name it with your prefix, such as MyMod_Singleton.
    • SaveGameActorTickable is a child of SaveGameActor that can tick. A timer is usually cheaper.
    • Ported from ASE with an Actor parent? File → Reparent Blueprint to SaveGameActor.
  2. Register it in your Mod Data Asset. The field is Server Extra World Singleton Actor Classes.

    Show me how
    • Open your Mod Data Asset → Server Extra World Singleton Actor Classes (ServerExtraWorldSingletonActorClasses) → add an element → pick your class.
    • The dropdown lists only SaveGameActor classes. If yours is missing, its parent is wrong.
    • Your test map's Primal Game Data Override must point at your PrimalGameData, or nothing in your mod loads.
    • After editing the Mod Data Asset, PIE can keep the old copy. How ARK finds your content explains the cache and its fix.
  3. Split Begin Play by machine. The server does the work; clients only show things. Put Switch Has Authority first.

    Show me how
    • Authority runs on the server, and in single player. Bind events, read the ini and start timers here.
    • Remote runs on clients, and only if the singleton replicates (step 6).
    • In single player and on a listen host, one machine runs both. I run the server branch first.
    • Loaded From Save Game (bLoadedFromSaveGame) is true when the singleton came back from the save. False means this world has never had it: the server owner just added your mod. Use it for first-time setup.
  4. Bind the game mode's events, then sweep who's already there. The game mode tells you when players spawn, die or join. Players already in the world never trigger those events.

    Show me how
    • On the server: Get Game Mode → Cast To ShooterGameMode → Bind Event to On Shooter Character Spawned (or Died, Post Login, Killed and the rest). Wire the cast result into the bind's Target. An empty Target listens to your own actor.
    • On Shooter Character Spawned fires on every spawn, not only the first: respawns and bed fast-travel count (Quellcrest). Anything you give there, such as a buff, is given again each time, so check for it first.
    • Right after binding, loop over the players who already exist and run the same setup. In single player, on a listen host and in PIE, the first player spawns before you bind (lessons §1).
    • Admin commands: bind the game mode's On Actor Custom Event, and admins can call your singleton with cheat ScriptCommand. Check the caller is an admin with IsPlayerAllowedToCheat before you act.
  5. Read your ini settings once, on the server. Store them in variables on the singleton. Everything else asks the singleton. The next section explains the nodes.

  6. If clients need it, make it replicate. By default a singleton exists only on the server. Four settings send it to every client.

    Show me how
    Class Defaults setting Property What it does
    Replicates bReplicates clients get a copy at all
    Always Relevant bAlwaysRelevant every client gets it, wherever they stand
    • Leave Net Load on Client and Rep Graph Behavior alone. Older guides tick them, but they do nothing for a spawned singleton. Net Load on Client is for actors placed in a map.

    • Then mark the values clients need Replicated, or RepNotify when the client must react. Set them on the server only.

    • Its Begin Play now runs on every client too, which a class default edit needs (Changing vanilla content).

    • Clients still can't call Run on Server events on it; they don't own it. Use the net exec route in Works in PIE, not on a server.

  7. Let other actors find it, and expect it to be late. Your buffs and structures fetch the singleton when they need a value. Nothing guarantees which spawns first.

    Show me how
    • Get Actor of Class with your singleton's class, then cache the reference.
    • If it isn't valid yet, try again on a short timer. At server start, a buff on a creature can easily beat it.
  8. Test it on a server. PIE hides most singleton mistakes. Check the log, then restart.

    Show me how
    • Log with Print Message in Shipping Build, prefixed [MyMod]. Print String is stripped from shipping builds.
    • Test with Net Mode Play As Client, then a late-joining second client, then a local dedicated server (Works in PIE, not on a server).
    • Restart the server and check your values came back.

Settings your mod reads from the ini

Server owners configure mods in the server's ini files. A mod can read them but can't ship them, so document each key and its default on your mod page. Reads only work on the server, where the game mode lives.

Where the keys go

Your keys live in GameUserSettings.ini, under a section named after your mod:

; <Server>\ShooterGame\Saved\Config\WindowsServer\GameUserSettings.ini
[MyMod]
GiftOnJoin=True
TimerMinutes=30
DamageScale=1.5

The section is the name in brackets, without the brackets. The option is the text left of the equals sign.

The nodes

All of these are on ShooterGameMode. Get it with Get Game Mode and a cast.

Node Reads If the key is missing
GetIntOptionIni a whole number returns 0
GetFloatOptionIni a decimal number returns 0.0
GetBoolOptionIni true or false returns the default you pass in
GetStringOption text returns empty text
TryGetIntOptionIni, TryGetBoolOptionIni the value, plus whether the key was there returns false
InitOptionInteger, InitOptionFloat, InitOptionBool, InitOptionString nothing; writes the key into the ini if it's missing —
GetIniArray (on ShooterGameState) every line of one section an empty array

Modders report that GetIniArray reads Game.ini, while the option nodes read GameUserSettings.ini.

Telling "not set" from zero

A missing number reads as 0, so 0 can't mean "use my default". I use one of three fixes:

  • Make 0 invalid and swap in your default when you get it. Clamp every value to a sane range anyway.
  • Read it as text first with GetStringOption. Empty means unset; otherwise read the number.
  • Use a Try node for whole numbers and booleans.

The Init nodes write your default into the server owner's file when the key is missing. Modders split on that. It skips 0 and false, and a default it already wrote never changes when you change yours.

Testing ini values in the DevKit

The DevKit reads its own GameUserSettings.ini when it starts and writes it back when it closes. Close the kit before you edit that file, or your edit is lost. Search the DevKit folder for the file name to find the one PIE uses.

To save restarts, some modders feed a fixed value in the kit. Is Shipping into a Select node picks the ini value live and a literal in the editor.

Note

Console single player has no ini at all. If your mod must be configurable there, add an in-game menu that saves to SaveGame variables or a SaveGame object (How to save your mod's data), and treat ini values as overrides.

How the pieces connect

This asset Field or call Points at
Mod Data Asset Server Extra World Singleton Actor Classes your singleton
Your singleton parent class SaveGameActor or SaveGameActorTickable
Your singleton bind on ShooterGameMode player and world events
Your singleton Get…OptionIni the server's GameUserSettings.ini, your section

The settings that matter

What you're looking for Where
Reach every client Replicates, Always Relevant
First run in this world Loaded From Save Game, false on the first spawn
Keep a value over a restart the variable's SaveGame tick box
Admin commands the game mode's On Actor Custom Event

Common mistakes

My singleton isn't in the dropdown

Its parent is Actor. Reparent it to SaveGameActor (step 1).

My singleton never runs

Check it's in your Mod Data Asset, and that the test map's Primal Game Data Override names your PrimalGameData. Then clear the cache (How ARK finds your content).

My singleton runs twice

In single player or on a listen host, both branches run on one machine, so split by authority (step 3). A replicated singleton also runs Begin Play on every client. Modders also saw a DevKit bug where Standalone PIE printed a singleton's Begin Play twice; switching Net Mode and back cleared it.

Players who were already there don't get my setup

You bound On Shooter Character Spawned after they spawned. Sweep existing players right after binding (step 4).

My ini value is always the default

Check these in order:

  1. You read it on a client. Read on the server and replicate the value (steps 5 and 6).
  2. The section or option name doesn't match. The section has no brackets in the node.
  3. The key went into Game.ini. The option nodes read GameUserSettings.ini.
  4. You edited the DevKit's file while the kit was open, and it wrote the old one back.

My buff can't find the singleton at server start

Nothing promises it spawns first. Retry on a short timer until it's valid (step 7).

Clients never see the singleton's values

It doesn't replicate. Set the four settings in step 6.

My singleton's variables reset after a restart

Tick SaveGame on the variable and set it on the server. See How to save your mod's data.

Check it worked

  1. On a local dedicated server, your [MyMod] line prints once at start.
  2. A player who joins gets your setup, and so does a late second player.
  3. A changed ini value takes effect after a restart; a deleted line falls back to your default.
  4. A client sees the replicated values, and SaveGame values survive a restart.

Watch

Go deeper

Sources

  • DevKit files, read offline on 2026-11-06 (UE 5.8.1): From the game module's reflection data: UModDataAsset.ServerExtraWorldSingletonActorClasses and the same field on UPrimalGameData, both typed as a list of ASaveGameActor classes; ASaveGameActorTickable as a child of ASaveGameActor; APrimalPersistentWorldData and the vanilla boss arena managers as SaveGameActor children; UPrimalActor.bLoadedFromSaveGame; AShooterGameMode.GetIntOptionIni, GetFloatOptionIni, GetBoolOptionIni (with a default input), GetStringOption, TryGetIntOptionIni, TryGetBoolOptionIni and the four InitOption… nodes; AShooterGameState.GetIniArray.
  • My other pages: lessons §1, §5, §7 and §9 and tutorials §5 (InitOption… skipping defaults; the DevKit rereading its ini).
  • What modders report: the SaveGameActor parent and one-per-class check (October to December 2023); the Standalone double print (December 2023); spawn order and retrying (January 2024); missing keys as 0 (November 2023, January 2024); GetIniArray and Game.ini (October 2024); testing ini values in the kit (December 2023, December 2025).
  • Videos under Watch are creators' tutorials, not checked against the kit. ZenRowe's is ASE-era.
  • Community knowledge from the ARK Modding Community Discord (discussions from October 2023 to May 2026), found with Overseer. Threads (they open for server members): SaveGameActor and the one-per-class check (October 2023), the singleton list and its saving (October 2023), Standalone runs Begin Play twice (December 2023), spawn order and retrying (January 2024), missing keys read as 0 (January 2024), Init nodes and reading as text (November 2023), GetIniArray and Game.ini (October 2024), testing ini values in the kit (December 2023).
Where this page's information comes from

Applies to: ASA DevKit as of November 2026 (UE 5.8.1); ASE where noted

the DevKit's own classes, the community Discord and creators' videos (see Sources)

Esc

↑ ↓ move↵ openCtrl ↵ new tab