Skip to content

Home

Jump to bottom
joric edited this page Nov 28, 2025 · 900 revisions

Welcome to the SupraTools wiki! Also see my Supraworld, SupraMods and CUE4Parse.CLI wikis.

Installation

Manual

  • Download latest UE4SS-RE from UE4SS-RE experimental-latest (first UE4SS*.zip from the Assets section).
  • Copy ue4ss folder and dwmapi.dll to Binaries/Win64/, (i.e. Win64/ue4ss/ and Win64/dwmapi.dll).
  • Copy (symlink) repository root to ue4ss/Mods/SupraTools/ (i.e. Win64/ue4ss/Mods/SupraTools/Scripts/main.lua, etc.).
  • Edit engine version in ue4ss/UE4SS-settings.ini for UE 5.6.1+ games (Supraworld 7708+), e.g:
[EngineVersionOverride]
MajorVersion = 5
MinorVersion = 6
  • Run the game.
  • Check ue4ss/UE4SS.log for issues.

Experimental UE4SS-RE works for UE4 games as well. Actually, most of the scripts work with other Supra games: Supraworld, Supraland, Supraland Crash and Supraland: Six Inches Under (just leave the engine version blank for autodetect).

Vortex

This may be VERY outdated at the moment, as I'm waiting for the game update and working on a game extension.

Game extension is pending (#18426), you can download files manualy and drop them into Vortex, it's the easiest way.

There are other mods in development, that may need Vortex support, namely:

Issues

Build 9016 introduced a 0,0,0 teleporting bug. Disabling UnblockEA script doesn't fix the issue. It happens rather random, every few minutes. Looks like a broken anti-UE4SS sentinel code in the game, that needs to be dealt with.

  • It happens with a completely disabled Supratools Mod, just due to UE4SS alone. Completely clean UE4SS, no mods.
  • Player randomly teleports to 0,0,0 during the game. It happens almost instantly, if player is inside EA volume.

It's currently patched. Tested workarounds:

  • Disabled Timer_StopScriptsTurningOffCollision with K2_ClearTimerHandle. Still occasionally teleports.
  • Optionally, you can destroy EA volumes with K2_DestroyActor with all their timers. Still teleports sometimes.
  • Added player position tracking code and teleporting back from 0,0,0. This fixes all the remaining issues.

Development

  • Enable EU4SS GUI with GuiConsoleEnabled = 1, GuiConsoleVisible = 1. You can use Ctrl+O to toggle console.
  • Set bUseUObjectArrayCache = true to enable the Live View tab, so you could search for objects and call API functions.
  • Export game API functions with Dumpers - Generate Lua Types (dumps in ue4ss/Mods/shared/types to study).
  • Export game resources with FModel (you can generate mapping file from UE4SS Dampers - Generate .usmap file).
  • Optionally, dump the full list of objects to ue4ss/UE4SS_ObjectDump.txt with Console - Dump Objects and Properties.
  • Study UE4SS experimental release documentation, https://docs.ue4ss.com/dev/index.html, it really helps.

Shortcuts

Shortcuts are subject to change, I'm leaning towards using a single "C" for noclip mode and maybe combining "G" (grabbing objects) with remote control. Keys without modifiers affect typing in console, need a way to detect is game console is open.

Script Shortcut Comment
FastTravel.lua F Fast Travel (teleport to mouse location on the game map)
SuitRefill.lua Alt+F Sponge Suit Refill (first fill is manual). Also Ctrl+F. Formerly Alt+R.
DebugCamera.lua MMB Toggles Debug Camera mode, LMB to teleport player to mouse target
RemoteControl.lua Alt+RMB Migrating to Alt+E. Remote Control (unlocks doors, opens boxes, etc. from distance)
SpawnThings.lua Ctrl+LMB Spawns things at cursor. Supports Alt+Z/X/C/V. Alt+Shift+R to rotate. Alt+Z to Undo.
UnblockEA.lua None Unblocks Early Access walls on load (sets wall collision to false)
GameSettings.lua ~ Adds console commands such as gravity, speed, etc.
GrabObject.lua Alt+G Grabs objects (eggs, hats, magnets) from distance. Sometimes grabs statics.
SkipCutscenes.lua Alt+U (Unskippable) Stops cutscenes, removes triggers (may break the game sequence)
GameStats.lua Alt+O (Objectives) Tries to add in-game UI, needs FText AOB (FText is not supported for 5.6).
AutoCollect.lua Alt+P (Pickup) Picks up all coins and tries to collects all secrets on the map automatically.
Minimap.lua Alt+M (Since 1.0.3) Shows secret locations/items. Updates in realtime. Works for all games.
PlayerProperties.lua ~ (Supraland only) Adds poke command to console, e.g. poke Happy? true.
Inventory.lua ~ Grant/Deploy substitute. Uses add/drop commands, type add or list to list items.

Obsolete scripts (removed in 1.0.3). All inventory-related stuff moved to Inventory.lua (add/drop commands).

Script Shortcut Comment
GrantAbilities.lua Alt+I (Inventory) Grants all abilities, adds grant/revoke, e.g. grant shield.
DeployItems.lua ~ (Supraland only) Adds deploy command and item aliases, e.g. deploy shell.

Ctrl+R is usually reserved for scripts reloading. Newest functionality may be unpublished, use repository for the latest version.

To search objects by name in GUI console, set bUseUObjectArrayCache = true in UE4SS-settings.ini. To show GUI console use "Ctrl+O" or GuiConsoleEnabled = 1 and GuiConsoleVisible = 1.

Debug Camera

Toggles debug camera on middle click (since 9016 it inteferes with "Binoculars"), teleports on left click, fly speed on scroll wheel. Uses built-in UE toggledebugcamera (rather, enabledebugcamera / disablebugcamera) cheat via UE4SS cheat manager. I've made a little patch that allows the camera to untoggle (see #514).

It's still crashes pretty consistently on teleporting. FastTravelAnywhere Stalker 2 mod uses the same guarding schema, a delay and a game thread wrapper, somehow it helps, but it's not a 100% reliable. Later UE4SS versions seem to be more stable, at least on reloading the scripts. Upd. pc.Pawn.RootComponent:K2_SetWorldLocation(loc, false, {}, true) seems safer.

I could try debugging it but it doesn't always save a crash dump. The idea is to look at the local/auto variables in VS at different functions in the call stack and see if it makes sense. The UE4SS Unreal submodule is open source, but the game is not. Probably it's possible to generate a game PDB with binfold, I'll check it out later.

Beware of breaking changes in UE4SS, such as #1047 and #1050. I had to replace built-ins with getPlayerController.

Inventory

Replaces grant/revoke grammar with add/drop. Latest inventory.lua can spawn chips and eggs (chip/egg commands).

  • To get a full list of inventory just use commands list or add without parameters.
  • You can also use find command from FindAsset.lua, e.g. find inventory_ _c and find equipment_ _c.
  • Spawn eggs/chips with egg <inventory> and chip <inventory> commands.

spawn_chip

Fast Travel

Open map, select location, press F. Type summon ShopItem_PlayerMap_C in the console if you don't have a map.

fast_travel.mp4

Spawn Things

Version 1.0.2+ introduces level editor. Use Alt+Z/X/C/V to undo/cut/copy/paste stuff, Alt+R to rotate. Future updates possibly will use Alt+W/A/S/D to move stuff. All actions are saved to a text file in the documents directory, you may delete or edit this file in case of issues.

The things save to %LOCALAPPDATA%/<GameName>/SpawnThings.txt" and spawn on start. Press "Alt+Z" repeatedly to clear the file.

hide|/Supraworld/Maps/Supraworld.Supraworld:PersistentLevel.DoorPiston_C_UAID_7085C2B20F0ED2D300_1834145250
spawn|HealthDispenser_C|6438.330897,1207.239025,320.682895;0.000000,-89.999999,0.000000;1.000000,1.000000,1.000000
spawn|PressurePlate_C|7874.755105,729.017278,320.673916;0.000000,-101.250002,0.000000;2.000000,2.000000,2.000000
spawn|Spruce1|5863.685896,551.726929,320.690541;0.000000,30.937500,0.000000;1.000000,1.000000,1.000000
rotate|SpawnedThings_0001|90.000000

Available actions are spawn|name|loc;rot;scale (Alt+V), rotate|name|yaw (Alt+R), and hide|name (Alt+X) more TBD.

  • Also you can copy/paste stuff using mouse keys: Alt+RMB - copy, Alt+LMB - paste (useful in Debug Camera).

You can't copy objects that don't have line trace collision, but you may edit the file (careful with size):

spawn|SecretVolume_C|0,0,0;0,0,0;15,15,15
spawn|LiquidVolume_C|0,0,0;0,0,0;1,1,1

Puzzle clouds (PuzzleCloud_C) wobble after actor:CloudAppear(), don't know how to fix just yet.

Use reload command in the game console to reload things (currently in repository only).

Suit Refill

Apparently, the amount of liquid is stored in double, as 3FF0 is high 16 bits of double 1.0. Addresses may vary.

Cheat Engine, search for 2 bytes, 3FF0 and 0 repeatedly. Freeze the value at 3FF0 (means sponge suit is full). 
<?xml version="1.0" encoding="utf-8"?>
<CheatTable CheatEngineTableVersion="46">
  <CheatEntries>
    <CheatEntry>
      <ID>0</ID>
      <Description>"Infinite Suit"</Description>
      <ShowAsHex>1</ShowAsHex>
      <VariableType>2 Bytes</VariableType>
      <Address>1DC71BDE6EE</Address>
    </CheatEntry>
  </CheatEntries>
  <UserdefinedSymbols/>
</CheatTable>

Using UE4SS scripting to refill Equippable_SpongeSuit_C is much easier, you just call an API function.

If you don't have a suit you can spawn it in UE4SS game console (~) with summon Shopitem_SpongeSuit_C.

You can dump all API functions using UE4SS GUI console (Generate Lua Types in the Dumpers tab).

Game Stats

Adds widgets to screen. Currently there is no UE5.4+ FText signature built in UE4SS so you have to create a file ue4ss/UE4SS_Signatures/FText_Constructor.lua with this content (e.g. see Deadly Days Roadtrip):

function Register()
    return "40 53 57 48 83 EC 38 48 89 6C 24 ?? 48 8B FA 48 89 74 24 ?? 48 8B D9 33 F6 4C 89 74 24 30 ?? ?? ?? ?? ?? ?? ?? ?? 7F ?? E8 ?? ?? 00 00 48 8B F0"
end

function OnMatchFound(MatchAddress)
    return MatchAddress
end

Without that FText() constructor just crashes, it cannot be guarded or anything so I check for this file and UE version.

Adding game completion stats to screen is one of the most wanted features. Press Alt+O to toggle stats.

Untitled

Minimap

Added in 1.0.3. Toggles on Alt+M. Works in all games.

photo_2025-10-13_12-49-44

Later minimap version uses a rotating canvas (Supraworld HDR images are not transparent). Use Ctrl+Alt+M to cycle positions.

Screenshot 2025-10-17 153610

Grant Abilities

Grant Abilities is deprecated, replaced with Inventory.lua (click to expand)

There are few abilities that have shop item interface and can be spawned in game console, e.g summon ShopItem_PlayerMap_C.

  • Spark ability ("Use pointy metal ends to zap through them."), doesn't seem implemented in 7925.
  • Mind Vision ability can be obtained from the egg in the vacuum machine, you can look through eyes of the possessed pawn.
  • Mind Posession (upgrade to MindVision that adds controls) doesn't untoggle, so I commented it out. There's MindPosession egg with but it's empty.
  • Force Cube is legacy ability, so it cannot be granted with Lyra. You can summon it with summon ForceCube_C.
  • Some abilities stack, e.g. Inventory_JumpHeightDouble_C, or Inventory_Dash_C (you can have infinite dashes).

Shop items available for summon in game console (other abilities are probably constructed):

ShopItem_BuyEggOpener_C
ShopItem_HealthQuarter_C
ShopItem_SolverGuidePage_C
ShopItem_PlayerMap_C
ShopItem_SpongeSuit_C
ShopItem_SpongeSuitCapacity_C # does not spawn
ShopItem_FlyingToTarget_C # does not spawn
ShopItem_ShopBigHeart_C
  • The mods adds grant <ability> and revoke <ability> commands. You can search for anything with find <words>.
  • Type grant or revoke and press Enter in game console to show available short names to grant/revoke.
Supraworld uses Lyra ability system. There are inventory manager and equipment manager.
Inventory item displays in your menu, it applies on restart, but in runtime you also need an equipment item.
If someone tells me out how to construct shopitems or use an unified API call that'd be swell.
You can use grant console command to grant inventory/equipment by full path.

Notable abilites are Inventory_Dash_C (you may have infinite dashes) and Inventory_BlowgunBlowTimeUnlimited_C.

You can use full paths, e.g. grant /Supraworld/Abilities/Shield/Equipment_Shield.Equipment_Shield_C.

Pictures

Pictures (click to expand)

shield
Shield ability

abilities
Abilities menu

supraworld_spawning
Spawn Things

level-editor
Level Editor

player properties
Player Properties

Scripting

  • Debug camera FindFirstOf("DebugCameraController") needs valid (reapplied) CheatManager to untoggle (#514).
  • Console teleport DebugCameraController.CheatManager:Teleport() works, but cannot teleport through the walls.
  • The K2_TeleportTo function is unsafe, has to be guarded with ExecuteInGameThread and ExecuteWithDelay.
  • The Pawn.RootComponent:K2_SetWorldLocation function is muchs safer, but still occasionally crashes.
  • Avoid FindFirstOf("Character") for getting a player, because it's also a newly-created enemy in the fight scenes.
  • Use actor:GetFName():ToString() to get a short name (#1030).

Console Commands

UE4SS enables in-game console (~), but the standard console cheats, such as fly and ghost usually don't work and toggledebugcamera doesn't untoggle (#514), that's why you need scripts included in this mod. Built-in commands are:

  • You can dump object properties in game console as dump_object PlayerMapActor_C.
  • Use summon to spawn assets at player location, e.g. summon ShopItem_SpogeSuit_C.
  • Use teleport to teleport to cursor in debug camera mode (uses navigation mesh).
  • Use set to set object properties, e.g. set FirstPersonCharacter_C_2147479994 Happy? true.

BP Mods

Used in the experimental minimap for the circular clipping material. See https://github.com/joric/SupraMods/wiki

References

Related Projects

UE4SS

Cheat Engine

Other

Clone this wiki locally