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

Installation (Players)

1. Extract this archive.
2. Copy included folders/files into your game’s UE4SS Mods folder.
3. Confirm these paths exist:
   • ue4ss/Mods/S2ML/...
   • ue4ss/Mods/shared/S2MLBridge.lua
4. 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.