DevKit and modding
Modding lessons
Last researched November 4, 202613 min read
Sources for this page
Applies to: ASA DevKit as of November 2026 (UE 5.8.1)
my own modding guides and my reading of the 5.8.1 game's compiled code and Blueprints, checked in Play In Editor and on real saves (not published; see where these pages come from); DevKit video tutorials by Jeremy Stieglitz (official, 2024), Quellcrest, SlayerXtreme, Mist3r Trixt3r, WM Plays and ZenRowe (transcripts read 2026-11-04; listed in What the video tutorials teach)
Confidence:AOfficial: Studio Wildcard, patch notes or in-game textBRead from the game or DevKit filesCInferred by comparisonDCommunity-measuredEUnverified
The general lessons from my modding guides: engine facts, traps and conventions that apply to any ASA mod. Nothing here is specific to one of my mods. Everything is conf. B (read from the DevKit's files and compiled code, or observed in Play In Editor) unless marked.
Lines marked Tutorials come from DevKit videos, which are collected in What the video tutorials teach: conf. D for creators, conf. A but dated February 2024 for Jeremy Stieglitz's official overview. I have not tested them. Where a video does something this page advises against, the rule stays and the note says why.
1. Setup and registration
- Every mod is a PrimalGameData + ModDataAsset pair. The PrimalGameData should derive from
PrimalGameDataARKNX_BP(every live official mod does), setModNameand pointAdditionalModDataAssetat the mod's ModDataAsset. - The templates leave traps. Every Create Mod template sets
ModName = 'cfeditor', and a hand-copied PrimalGameData still points at the template's ModDataAsset. 101 of 153 community ModDataAssets in my census still saycfeditor. - How mod data merges: arrays append (mods stack), maps overwrite on a duplicate key (later mod wins), booleans
OR (one mod flips a flag for the whole server), and
DefaultGameModegoes to whichever mod merges last. So a general mod must never set server-wide switches such asOverrideServerPhysXSubsteps,bPreventPhotoModeorbForceServerUseDinoList. Whether "last" follows the server'sActiveModsorder is untested. Tutorials: Quellcrest found a sparse data override manager did not stack when registered in the ModDataAsset and registered it in the PrimalGameData instead (conf. D, UE 5.5, 2025). That puts it in a field where the last mod wins; needs a 5.8.1 check before anyone copies it (tutorials §5). - A mod mounts at
/<ModName>/, not/Game/Mods/.... A wrong root compiles into silent no-ops. - No
.or-in package names inside any Content folder: ARK scans every mod's Content at PIE start, and a file likeX.backup.uassetis fatal. Keep backups outside Content. - ASA cooks your whole mod folder. The CurseForge cooker packs everything in it, referenced or not, so an asset
you only spawn or load by path from code still ships. Listing code-only assets in
ExtraResourceswas the ASE rule; ASA doesn't need it. What it does leave out is anything outside your mod folder. Don't put a level inExtraResourceseither: since UE 5.5 that fails the cook. (Modding Discord, 2024-04 and 2024-12; level cook failure 2025-06) - Build on vanilla, never overwrite it. None of Wildcard's mods modifies or shadows a
/Gameasset: use a subclass plus a remap,AdditionalDefaultBuffs, theAdditional*arrays and native opt-in flags. Copied vanilla Blueprints go stale (one copied crafting station froze at 84 recipes while the vanilla list kept growing). Tutorials do instead: several copy the Smithy, a storage box, their inventory components, or a dino-settings or death-inventory class, partly because a child cannot edit an inherited component's graph (conf. D). I don't, because a copy stays frozen at the day you made it; for stations,ForceAllowCraftingForInventoryComponents, the inventory component'sImpersonateand the ModDataAsset'sAdditionalStructureEngramsgive vanilla behavior without a copy (tutorials §8). One video adds a rider socket to what looks like the vanilla Dodo mesh (conf. E); I don't edit/Gameassets at all, since such an edit probably does not survive the cloud cook (unverified); copy the mesh into the mod instead. - The common server-mod skeleton: a
SaveGameActorchild registered inServerExtraWorldSingletonActorClasses(one per world), which binds the game mode'sOnShooterCharacterSpawnedto give each player a buff, andOnActorCustomEventto receivecheat ScriptCommandadmin commands. The singleton must also sweep players who already exist, or listen-server hosts and single-player players are missed. Tutorials: Quellcrest hits the same timing problem in PIE and single player and works around it with a delay and "get all controllers" after the bind (conf. D). - Map and logic as separate mods: Survival of the Fittest ships its map and its game mode as two projects; the map references only vanilla classes and the logic mod remaps them, so either can update alone.
2. Blueprint traps
Most ARK Blueprint failures are silent: a clean compile and logic that returns defaults.
- One bad function can stub the whole Blueprint, so every function returns its output defaults with a clean
compile log. Triggers seen: a declared
ReturnValueon a function that really uses an out parameter, a static UFUNCTION on an Actor class, a cast to a class with sparse class data metadata, two links on one exec output pin. Start every test with a canary call whose right answer is not a default. - Hooks need their gate flags. Many native events fire only when a
bUseBP*flag is set in class defaults; buffs have over 100 such gates, and some live in sparse class data. Even vanilla ships dead overrides: 24 of 366BPDeactivatedand 31 of 315BuffTickServeroverrides have the gate off. Some gates break the naming rule (UseBPAdjustOutputDamagewith nob;bUsePostAdjustDamage;bNotifyDamage). - Class-default edits need a compile after them, or new spawns do not get them; and editing a class default never changes creatures, items or structures already saved.
- Pins bind by name. A renamed parameter only warns ("Input pin X ... no longer exists") and keeps its default. Read warnings, not just errors.
- UE 5.8 reverted some pasted defaults (an
Add_IntIntB of 0 came back as 1); audit math nodes whose C++ default is nonzero. Promotable math nodes drop to single precision, which ruins game-time values around 1e8 s. - An event dispatcher bind with no Target listens to yourself.
OnActorCustomEventexists on every actor, so an unwired bind compiles silently against your own actor instead of the game mode. - Exec and loop traps: impure nodes off the exec chain are pruned without error; a Return in a Sequence's first branch ends the function; ForEach over a pure getter re-evaluates it each pass (destroying inside skips every other element); a While with no guard runs to "Runaway loop detected" and crashes.
Delayin an event that can fire again reuses the latest call's parameters, so players spawning together miss setup. Use a queue on a timer.- Soft loading: "Convert asset" returns None unless the class is loaded, and PIE shares editor memory so async
paths cannot be proven there.
BPLoadClassresolves Blueprint paths only. Hard casts to DLC or map classes load those packages. - Struct edits: a Make node with one pin wired resets every other field to native defaults (a "Make WeaponData" with one pin gives a pickaxe a 20-round clip). Copy and use Set Members in Struct, and base new values on the class default so changes do not compound.
- Some hooks want a delta.
BPModifyArmorValuereturns a contribution, not a total. - Reachability is three flags: get needs BlueprintVisible, set also needs not-ReadOnly, call needs BlueprintCallable. Native static arrays and uint16/uint32 struct members cannot be read in Blueprint.
3. Testing and debugging
- PIE is server and client in one process (worlds
UEDPIE_0andUEDPIE_1). It hides replication mistakes, logs in as a new player every run (no relog), shares editor memory, never delivers server-given items to a "Play As Client" view, and its sessions decay after about 10 to 16 creature spawns. Game time starts at 200,000,000 s in PIE on 5.8.1 (the shipping game in single player starts at 100,000,000), so store "now plus the delay" rather than assume a start value (PIE crash reports, checked 2026-11-06; testing) - Mod data loads only on a map whose "Primal Game Data Override" names your PrimalGameData; the stock test map loads none. After a ModDataAsset edit PIE can keep the old data: set the override to None, run PIE once, restore it. Tutorials: Quellcrest describes the same fix, and SlayerXtreme's "new engrams do not show in PIE" is the same bug (conf. D).
- Persistence tests need
-ForceSave -ForceLoadon the editor command line; otherwisecheat SaveWorldwrites but the next run never loads. - Known PIE crashes: opening the inventory while holding any weapon but fists (StopFire stack overflow);
audio-mixer hangs on PIE exit in 5.8.1 (use
-nosound); saving an asset whose actor is in a running PIE level; switching levels with Blueprint editors open. - The first Blueprint editor of a session loads every function library and streams in much of the game (minutes, over 35 GB in one test).
PrintToServerGameLogwrites nothing unless the server runs with-servergamelog, setsbServerGameLogEnabled=True, or is official.- Rolled crate contents are never saved, and wild creatures re-roll on load: inspect loot in the inventory UI and test persistence on tames.
- Real release testing: a dedicated server with a remote client, a late joiner and a second nearby client; gamepad as well as mouse. One successful PIE run proves nothing about persistence or the console cook.
- Tutorials: a cooked build can be tested before publishing. Once it shows "ready for review", linking a game
account in CurseForge puts it in the game's My Mods list, and a test server can load it as the project ID with a
-devsuffix (conf. D; tutorials §4). Test spawn counts on a dedicated server too: single-player stasis skews them (conf. D).
4. Networking and replication (engine facts)
From the 5.8.1 replication setup, as I decoded it from the compiled code:
- ARK runs its own replication graph, with 100 m dynamic and 200 m dormant grids.
- Most state replicates once, at spawn (
COND_InitialOnly): 212 of 245 game-state properties, 22 of 25 on structures, all 27 on containers, 59 of 94 on dinos. Later changes travel throughMulticastProperty, which is one client RPC through every connected player's controller. So 50 turrets pushing 8 properties a second to 20 players is about 8,000 RPCs a second. - The push model is live only on dinos, the character base, the status component and
TargetingTeam; dirty marks elsewhere do nothing. The working idiom is flush net dormancy, mark dirty, thenMulticastProperty. AShooterPlayerStateis owner-only. Other players' states never reach your client.- Most projectiles are not replicated: each machine spawns its own from a multicast, so an arrow is not one shared actor.
- The dormant budget is 800 replications per second per connection and drops to 0 while reliable RPCs on the player's controller or pawn are in flight, so reliable streams through the controller pause structure streaming.
- Multicasts miss late joiners. Persistent state belongs in RepNotify variables; multicasts are for one-off effects.
- Stasis stops ticking and replication for far actors, and on servers with structure hibernation, timers on structures pause; catch up from saved timestamps.
- Pick one clock per comparison. Network time is per server: right for a timer that lives on one server, wrong for anything that transfers. Use real-world UTC time (as a double) for those. (modding Discord 2024-03 and 2026-09)
5. Server trust and security
- A client can call any Server RPC on an actor it owns, with any arguments. Every server handler must re-check
the caller (admin via
IsPlayerAllowedToCheat, team, tribe rank, distance) and clamp every value. About half of 22 published mods I studied check admin or price only in the client UI. - Never let client or remote text reach a console command, and never take identity or rights as an RPC parameter.
- Anything in a
.uassetis public once uploaded, struct defaults included: webhook URLs, keys and test ids have shipped in published mods. Credentials come from the server's ini, defaulting to empty. - No personal data leaves a server without an opt-in ini key the server's admin sets, and HTTP calls go only from the server to URLs from the ini.
- Cap every queue and array that a client or an outside service can grow.
6. Engine updates
- 5.5.4 to 5.8.1 (2026-10-09):
BPOverrideHurtAnimgainedHitCompandHitBone, andChangedAITargetnow takesOldTarget, so overrides must be refreshed and recompiled; five ship-ramming properties were replaced by a ram-socket radius model and old values are silently lost; 26 properties became Blueprint-readable (for exampleDinoID1,DinoID2,OwningPlayerID); new hooks includeBPHandleInstigatorItemDrop,PeekDinoDataand the skill-tree reads. - UE 5.8 saves carry a newer object version and make a
PreUpgradeBackupwhen loading an old save; back up test worlds first. Offline package readers written for 5.5 fail on 5.8.1 packages (header layout changed). - Routine after each DevKit update: diff the native classes, reopen every Blueprint that overrides a changed hook, read the compile warnings, re-run canary and round-trip tests, then a dedicated-server test.
7. Reading the game's data (for tool authors)
- Sparse class data: Many creature, item and structure numbers are not on the class default object but in a
second tagged block after it (for dinos
FPrimalDinoCharacterSparseClassData): gestation speed, cuddle intervals, the stored imprint maturation time, mating times, mutation settings, manybUseBP*gates, structure flags such asbSnappingRequiresNearbyFoundation. A tool reading only class defaults reports them as missing. Tutorials: at runtime a sparse-data value is shared by the whole class, so setting it on one actor changes every instance; per-actor values go through aSparseDataOverrideManagerchild (conf. D, UE 5.5; tutorials §5). - Merge down the Blueprint chain, parent first, field by field. A child stores only the fields it changed, in
class defaults, sparse data, static arrays (
ItemStatInfos[i]) and loot override sets alike; an unset field means the parent's value, not the struct's default. - Config keys come from two places. Game.ini keys are reflected
Configproperties (259 onAShooterGameMode), but the familiar[ServerSettings]keys (HarvestAmountMultiplier,TamingSpeedMultiplier,DifficultyOffset,XPMultiplier,ActiveMods,RCONPort) are not reflected and are read imperatively; they exist only as string literals in the server executable. - Mods read settings through the game mode's
Get*OptionInihelpers,ShooterGameState.GetIniArray(a whole Game.ini section) and the custom game mode'sGet*ValueFromINI. Only 2 of the 6 breeding multipliers are Blueprint-visible on the game mode, so reading the ini is the reliable route. Never read a game mode setting on a client. - Structure decay timers are saved only when decay is on; with decay off, or a tribe member near in the last 120 s, the timer is written as 0 and the property is absent from the save.
8. System by system
Buffs. Children of Buff_Base die after 1 s unless DeactivateAfterTime is 0. Add buffs with
StaticAddBuff on the server (it returns None on a client); set up in BPSetupForInstigator; clean up in both
BPDeactivated and ReceiveEndPlay. bIsBuffPersistent does not save Blueprint variables. A buff on every wild
creature is one replicated actor per creature.
Creatures. Set colors
with ForceUpdateColorSets on the server, never material parameters (lost on save and for late joiners).
Tutorials: ZenRowe's ASE ModKit series swaps creature materials for a dissolve effect; that is fine because the swap
runs from a buff on every client and is a passing effect, not a color, so the color rule stands
(tutorials §7). Random
color IDs must come from 1..100 and 128..254. Melee damage needs a MeleeSwing notify state that triggers on the
dedicated server. MaxWalkSpeed lives on the movement component; tames use TamedWalkableFloorZ. Subclassing a
creature for one small change breaks breeding and other mods' class checks; a buff overlay is often better.
Breeding and traits. Incubation belongs to the egg item, not the parent. Imprint per cuddle uses the stored total maturation time. Twins at 0 still allow triplets. Gene trait tiers are stored 0, 1, 2. Bred babies get no gene traits by default, and wild creatures roll none in the DevKit unless you enable it.
Items. Identify items by ItemID; move them add-first,
remove-second; SavedDurability is a fraction and above 1.0 is legal; display stats through native
GetItemStatModifier. Stacks merge regardless of custom data. Never write vanilla custom-data names (Dino,
ItemTraitData, CustomEmbryoData and others). Saddles never break from damage (floor 0.1). Tutorials: custom item
data is an item's only per-instance replicated state; read it in BPPostInitializeItem and call UpdatedItem after
writing (conf. D; tutorials §5).
Weapons and damage. Damage lives on the weapon actor, the projectile or the
damage type, never on the item. WeaponConfig is neither replicated nor saved and is rebuilt on every equip. Damage
hooks pass unhandled damage through unchanged. No universal order between the damage layers has been established,
so each modifier must stand alone.
Structures. Returning "allowed" from BPIsAllowedToBuild
erases every vanilla placement rule; pass the current reason through. Run setup from BPPostLoadedFromSaveGame as
well as on placement. Tiers are damage tables, not health. Overriding one snap point means owning the whole list.
LimitMaxStructuresInRangeTypeFlag is a count, not a mask.
UI and input. Create UPrimalUI
screens with an owning player and close them with RemoveFromViewport or CloseWithAnimation, not
RemoveFromParent on the screen itself (vanilla menus still use it on child widgets). Blueprint input nodes consume by default, so binding Use on a buff can kill the E key. Use
OnPreviewKeyDown on ARK screens. A replacement item tooltip must still call BPGetItemDescription, or the Specimen
Implant breaks respawning.
Maps. Set the kill box and lat/lon grid for your map's
size. Server systems must not sit on spatially loaded actors. Client-side actor searches miss unloaded cells.
Disable vanilla zones (bEnabled = False) instead of deleting them. Start a map with the DuplicateSampleIsland
script. Tutorials do instead: the ASA mapping videos (2023 to 2025) start from Empty Open World and copy Island
actors by hand in a second editor; I don't, because the script is Wildcard's route and does the copying for you,
and the manual route is probably from before the script (my inference, conf. E). Their map-system and landscape
notes still apply (tutorials §9).
Console and cross-play. The server is always a PC program, so gameplay is identical for everyone and platform branches are for presentation only. Design for gamepad first. The DevKit contains no console memory budgets; keep textures small and streaming, and never hold big textures in always-loaded struct defaults (Wildcard's own code documents a 32 MB UI texture pinned that way).
Game modes and events. Only a server built for the mode sets DefaultGameMode;
layered events use a singleton. Public state comes from an always-relevant replicated actor. Cleanup destroys a
tracked list, never every actor of a broad class.
9. Before you publish
My full checklists are longer. The short version: real mod name and no
template leftovers; gates set; warnings read; tested on a dedicated server; no credentials, debug keys,
PrintString or copied DevKit content; textures capped (1024 is plenty for icons); every ini key documented with
its default, under one section named after the mod without brackets.