Subnautica2-API-Library (S2ML)

Nautilus-style UE4SS Lua API framework for Subnautica 2 modding.

S2ML is a shared modding library that provides stable, reusable APIs for common Subnautica 2 mod features: events, player access, inventory operations, item/recipe/tech registration, world helpers, save utilities, notifications, sounds, and runtime discovery tooling.

What is this?

S2ML is a dependency library for modders and an optional framework for players.

If you are a player: install S2ML when another mod says it requires it.
If you are a modder: use S2ML to avoid rewriting low-level UE4SS glue and build cleaner mods faster.

Key Features

Event-driven mod API (OnPlayerSpawned, OnFabricatorOpened, OnPlayerDeath, and more)
Player helpers (location, depth, movement, spawn readiness, utility vectors)
Inventory helpers (give/remove/count/containers/batch operations)
Item + recipe + tech registration framework
World helpers for spawning, querying, teleporting, and cleanup
Save/load helpers with fallback patterns for Early Access builds
Notification + sound wrappers
Runtime discovery tools (S2ML.Probe) for changing class/function names
Shared dependency bridge (S2MLBridge.lua) for child mods
Example starter mod (ModTemplate) included

Compatibility

Game: Subnautica 2 (Early Access)
Runtime: UE4SS Lua
Recommended UE4SS: 3.0.1
Engine target: UE 5.6 era runtime assumptions

Subnautica 2 is in Early Access. Internal class/function names may shift between updates.

Installation (Players)

Extract this archive.
Copy included folders/files into your game’s UE4SS Mods folder.
Confirm these paths exist:
- ue4ss/Mods/S2ML/...
- ue4ss/Mods/shared/S2MLBridge.lua
Enable S2ML in mods.txt:

S2ML : 1

Enable your own mod after S2ML:

S2ML : 1
YourMod : 1

Installation (Modders)

Reference S2ML from your mod:

-- YourMod/Scripts/main.lua
local S2 = require("S2MLBridge")
S2.RequireVersion("3.1.0")

S2.Player.WhenReady(function(PC)
    S2.Notify.Message("My mod loaded!")
    S2.Inventory.Give("Battery", 2)
end)

Included Modules (High Level)

S2ML_Core - logging, safety wrappers, lifecycle/version checks
S2ML_Events - pub/sub event bus + game hook wiring
S2ML_Player - pawn/location/depth/movement helpers
S2ML_Inventory - inventory and container operations
S2ML_Items - item registration/default patching/give fallback
S2ML_Recipes - recipe registration + fabricator injection flow
S2ML_Tech - unlock/query helpers
S2ML_World - spawn/query/teleport/destroy helpers
S2ML_Notify - HUD/message fallback pipeline
S2ML_Sounds - sound playback wrappers
S2ML_Save - save/load utility wrappers
S2ML_Assets - asset/object lookup helpers
S2ML_Config - key/value config helpers
S2ML_Time - delay/repeat/debounce/throttle utilities
S2ML_Probe - in-game discovery tooling

In-Game Tools

Keybinds

Ctrl+P - run full class/function discovery scan
Ctrl+I - inspect nearest actor
Ctrl+U - dump player inventory

Console Commands (via ConsoleHelper)

s2ml version
s2ml modules
s2ml give <item> [count]
s2ml save
s2ml tp <X> <Y> <Z>
s2ml tpf <distance>
s2ml depth
s2ml whereami
s2ml api
s2ml events
s2ml probe
s2ml inspect [class]
s2ml inv
s2ml debug
s2ml loglevel <TRACE|DEBUG|INFO|WARN|ERROR>
s2ml reset

Reporting Bugs

Please include:

Subnautica 2 version/build
UE4SS version
S2ML version
Reproduction steps
Relevant UE4SS.log lines

Known Limitations (Early Access)

Some game APIs are discovered dynamically and may require updates after patches
Recipe/tech/save internals can change between builds
UI/HUD/sound paths may vary by build and content updates

Versioning

Major - breaking API changes
Minor - backward-compatible feature additions
Patch - fixes and compatibility updates

Child mods should pin a minimum version with RequireVersion.

License

MIT

Credits

Created and maintained by forgeDMC. Community feedback and compatibility reports are welcome.

Subnautica2 API Library (S2ML)