OniMods

简体中文

A large-scale modular repository for Oxygen Not Included mod development:

• onim: Rust-based ONI mod development CLI (init/build/install/publish workflow)
• OniMcp: MCP server mod exposing colony state and safe operations to MCP-compatible clients

Compatibility warning: before 1.0.0, the OniMcp API can still introduce breaking changes. If you build derivatives, plugins, scripts, or third-party clients, pin exact versions and use runtime manifests (e.g. oni://tools/manifest) as the compatibility source of truth.

AI infrastructure & open-source support: OniMcp development and agent testing consume model API credits. If you need an OpenAI-compatible endpoint for your MCP client, LMM API Gateway is one available option. Its source code is hosted by TokenNotIncluded. Purchases help fund this work, while substantive issues, pull requests, and testing may receive API credits. OniMods remains open source and does not require this provider.

Table of Contents

• Project Overview
• Supported Modules
• Quick Start
• Quick Links
• Getting Started with onim
• Repository Layout
• Command Reference
• Development & Runtime Notes
• Compatibility
• Contributing
• Release Notes

Project Overview

The repository is organized as a two-part platform:

1. Dev Tooling Layer (onim)
   A developer experience layer for creating and shipping ONI mods.

2. Mod Layer (mods/)
   Concrete mod implementations and templates with explicit boundaries.

Supported Modules

Quick Start

cargo install --path .
onim setup
onim doctor
onim init MyMod
onim dev -m MyMod

Quick Links

• English ONI MCP docs: mods/OniMcp/README_EN.md
• Chinese ONI MCP docs: mods/OniMcp/README.md
• ONI MCP server changelog: mods/OniMcp/CHANGELOG.md
• Template changelog: mods/OniModTemplate/CHANGELOG.md
• CycleTrim changelog: mods/CycleTrim/CHANGELOG.md
• Read the full story: A Letter to Everyone

Open Source References

• Community reference project: zhuiyun.skill
• ONI mod ecosystem references: PLib
• ONI ecosystem patching: Harmony, FastTrack

ONI MCP Server

OniMcp is designed as a safe, MCP-native operations layer for Oxygen Not Included:

• world_editor: world-like text file editing workflow; apply SEARCH/REPLACE style edits to virtual save artifacts
• game_control: play speed, pause/resume, save/load orchestration
• navigation_control: camera, overlays, screenshot workflow
• building_control: building operations and utility routing
• orders_control: dig/sweep/clean/deconstruct flow control
• server_control: manifest, screenshot lifecycle, diagnostics, and session status

ONI MCP Server Design

• Publicly visible surface is intentionally compact and stable for MCP clients.
• Former aggregate entrypoints are internal operations used only by the virtual-file workflow; they are not registered as MCP tools.
• Operations are designed with explicit task framing and player confirmation in the operational flow.

See the full runtime docs in mods/OniMcp/README_EN.md.

onim

onim is the Rust CLI used by this repository to initialize, build, install, uninstall, inspect, and publish ONI mods.

Typical Development Flow

1. Install dependencies and initialize local config with onim setup
2. Scaffold mod with onim init
3. Iterate quickly via onim dev -m <mod>
4. Build/publish through onim build and onim publish

CycleTrim and OniMcp use the locked, headless workflow in docs/steam-publishing.md.

Repository Layout

.
├── onim.toml                     # onim config (default mod + aliases)
├── Directory.Build.props.example  # .NET config template
├── Directory.Build.props          # generated local config (not committed)
├── Cargo.toml                    # onim CLI project
├── src/                          # onim source
├── mods/                         # mod workspace
│   ├── OniModTemplate/           # reusable mod template (ModInfo + Patches/)
│   ├── OniMcp/                  # ONI MCP server
│   │   ├── ModInfo.cs            # entry only
│   │   ├── Patches/ UI/ Config/ Core/ Server/ Support/
│   │   └── Tools/{Core,Entry,WorldEditor,Shared,Impl}/
│   └── CycleTrim/                # performance mod
│       ├── ModInfo.cs            # entry only
│       ├── Core/                 # shared non-patch logic
│       └── Patches/              # Harmony patches
├── docs/                         # reference docs
└── scripts/                      # helper scripts and verification tools

Getting Started with onim

# 1) Install CLI from source
cargo install --path .

# 2) Discover game path and dependencies
onim setup

# 3) Verify the local development environment
onim doctor

# 4) Create a mod
onim init MyMod --author YourName --desc "Your mod description"

# 5) Development cycle
onim dev -m MyMod         # build + install to Dev
onim info                 # inspect installed mods

# 6) Release cycle
onim install -m MyMod     # Release install to Local
onim publish -m MyMod     # publish to Steam Workshop

# 7) Cleanup
onim uninstall -m MyMod   # supports scope flags

If this is your first run, create your local build config before the first build:

cp Directory.Build.props.example Directory.Build.props
# edit OniGamePath in Directory.Build.props to your local ONI installation

onim setup can also generate this config automatically.

Command Reference

Development & Runtime Notes

• Use semantic tasks and explicit short descriptions for all MCP calls.
• Prefer read-only verification for first-pass planning (status, safety checks, manifests).
• This project intentionally avoids pretending full autonomous gameplay can replace human oversight.

Current direction

• Move game operation toward virtual-file driven workflows
• Keep explicit confirmation and bounded operations in critical actions
• Maintain strict safety checks and compatibility surfaces between tool versions

Compatibility

• OniMcp is pre-1.0, so API surface can be unstable.
• For derivatives and integrations, pin exact versions and use runtime manifests as compatibility source.
• Use oni://tools/manifest for runtime verification.

Contributing

1. Open issue for scope and design first
2. Keep PRs focused to one coherent change
3. Add/update docs/changelog links when behavior changes
4. Confirm local workflow (onim setup, relevant verify scripts) before merging

Run python3 scripts/check_mods.py with Python 3 and .NET SDK 10 for the Mod
regression suite. See Mod testing for coverage and the
additional checks that require an installed game.

Dependencies

• Rust to compile onim
• .NET SDK to build ONI mods
• unzip and tar for packaging/install helpers
• Steam Workshop + ONI local environment for integration checks

Release Notes

• OniMcp releases are tracked in mods/OniMcp/CHANGELOG.md.
• CycleTrim history is tracked in mods/CycleTrim/CHANGELOG.md.
• Template changelog is tracked in mods/OniModTemplate/CHANGELOG.md.

License

This repository is licensed under the MIT License. See LICENSE.