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
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 asMyMod_Singleton. SaveGameActorTickableis a child ofSaveGameActorthat can tick. A timer is usually cheaper.- Ported from ASE with an
Actorparent? File → Reparent Blueprint toSaveGameActor.
- Content Browser → right-click → Blueprint Class → search
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.
- Open your Mod Data Asset → Server Extra World Singleton Actor Classes (
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.
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 withIsPlayerAllowedToCheatbefore you act.
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.
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 bReplicatesclients get a copy at all Always Relevant bAlwaysRelevantevery 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.
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.
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.
- Log with Print Message in Shipping Build, prefixed
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:
- You read it on a client. Read on the server and replicate the value (steps 5 and 6).
- The section or option name doesn't match. The section has no brackets in the node.
- The key went into
Game.ini. The option nodes readGameUserSettings.ini. - 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
- On a local dedicated server, your
[MyMod]line prints once at start. - A player who joins gets your setup, and so does a late second player.
- A changed ini value takes effect after a restart; a deleted line falls back to your default.
- A client sees the replicated values, and SaveGame values survive a restart.
Watch
- Ark Ascended Devkit: The Ultimate CCA (Singleton) Tutorial (my video). 1:46 making and registering it. 4:01 the authority split and Loaded From Save Game. 6:13 the game mode's events. 14:17 reading the ini. 22:33 script commands. 37:52 replicating a counter.
- Ark Survival Ascended - Dev Kit - Replication (Quellcrest). 0:04 making a singleton. 7:31 calling it with a script command.
- Ark Survival Ascended - Dev Kit - Blueprint Interfaces (Quellcrest). 12:41 no guarantee the singleton is loaded yet. 13:37 retrying on a timer.
- ASA Modding - Server Configuration Options (Mist3r Trixt3r). 7:07 the graph. 14:06 clamping values.
- Wildcard Workshop #6: Config Options (ZenRowe, ASE). 2:58 the Init nodes.
Go deeper
- How to save your mod's data: SaveGame variables on the singleton, and settings menus.
- Works in PIE, not on a server: ownership, replication and why ini reads fail on clients.
- Changing vanilla content without replacing it: class default edits from a singleton.
- How to make a buff: default buffs, and sweeping existing creatures from a singleton.
- The world and game mode reference: every game mode event and helper.
- lessons §1, §5 and §9: the server-mod skeleton, checking callers, documenting ini keys.
Sources
- DevKit files, read offline on 2026-11-06 (UE 5.8.1): From the game module's reflection data:
UModDataAsset.ServerExtraWorldSingletonActorClassesand the same field onUPrimalGameData, both typed as a list ofASaveGameActorclasses;ASaveGameActorTickableas a child ofASaveGameActor;APrimalPersistentWorldDataand the vanilla boss arena managers as SaveGameActor children;UPrimalActor.bLoadedFromSaveGame;AShooterGameMode.GetIntOptionIni,GetFloatOptionIni,GetBoolOptionIni(with a default input),GetStringOption,TryGetIntOptionIni,TryGetBoolOptionIniand the fourInitOption…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);
GetIniArrayand 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)