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), set ModName and point AdditionalModDataAsset at 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 say cfeditor.
  • 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 DefaultGameMode goes to whichever mod merges last. So a general mod must never set server-wide switches such as OverrideServerPhysXSubsteps, bPreventPhotoMode or bForceServerUseDinoList. Whether "last" follows the server's ActiveMods order 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 like X.backup.uasset is 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 ExtraResources was the ASE rule; ASA doesn't need it. What it does leave out is anything outside your mod folder. Don't put a level in ExtraResources either: 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 /Game asset: use a subclass plus a remap, AdditionalDefaultBuffs, the Additional* 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's Impersonate and the ModDataAsset's AdditionalStructureEngrams give 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 /Game assets 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 SaveGameActor child registered in ServerExtraWorldSingletonActorClasses (one per world), which binds the game mode's OnShooterCharacterSpawned to give each player a buff, and OnActorCustomEvent to receive cheat ScriptCommand admin 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 ReturnValue on 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 366 BPDeactivated and 31 of 315 BuffTickServer overrides have the gate off. Some gates break the naming rule (UseBPAdjustOutputDamage with no b; 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_IntInt B 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. OnActorCustomEvent exists 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.
  • Delay in 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. BPLoadClass resolves 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. BPModifyArmorValue returns 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_0 and UEDPIE_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 -ForceLoad on the editor command line; otherwise cheat SaveWorld writes 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).
  • PrintToServerGameLog writes nothing unless the server runs with -servergamelog, sets bServerGameLogEnabled=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 -dev suffix (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 through MulticastProperty, 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, then MulticastProperty.
  • AShooterPlayerState is 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 .uasset is 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): BPOverrideHurtAnim gained HitComp and HitBone, and ChangedAITarget now takes OldTarget, 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 example DinoID1, DinoID2, OwningPlayerID); new hooks include BPHandleInstigatorItemDrop, PeekDinoData and the skill-tree reads.
  • UE 5.8 saves carry a newer object version and make a PreUpgradeBackup when 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, many bUseBP* gates, structure flags such as bSnappingRequiresNearbyFoundation. 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 a SparseDataOverrideManager child (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 Config properties (259 on AShooterGameMode), 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*OptionIni helpers, ShooterGameState.GetIniArray (a whole Game.ini section) and the custom game mode's Get*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.

Esc

↑ ↓ move↵ openCtrl ↵ new tab