Skip to content

README.en.md

Latest commit

 

History

History
171 lines (127 loc) · 10.4 KB

README.en.md

File metadata and controls

171 lines (127 loc) · 10.4 KB
Raw

Scripts For Minecraft Server (SFMC)

Microkernel Companion Architecture & Modern Server Engineering Toolkit for Minecraft Bedrock (BDS)

CI Status version license node typescript npm modules bds

📚 Online Documentation · 📦 Module Index · 🚀 Quick Start Guide · 中文版本

💡 What is SFMC?

Scripts For Minecraft Server (SFMC) is a modern development framework and multi-process companion architecture engineered specifically for the official Minecraft Bedrock Dedicated Server (BDS).

Combining Minecraft's native Script API (SAPI) with a high-performance local Node.js companion supervisor, SFMC delivers a true production-grade engineering workflow to Bedrock server operations. It decisively resolves traditional ecosystem pain points: plugin fragmentation, data loss/corruption, lack of sandbox isolation, and frequent downtime caused by restarts.

flowchart TD
  subgraph Client_Layer ["Client & Tooling Layer"]
    CLI["sfmc CLI Console<br/>Multi-Process Supervision / REPL"]
    IDE["VS Code / Cursor Extension<br/>Incremental Watch / Hot-Reload"]
    QQ_Client["Community Ecosystem<br/>QQ Official Bot / OneBot 11"]
  end

  subgraph Companion_Layer ["Node.js Companion Supervisor (127.0.0.1 Loopback)"]
    DB_Svc["db-server (:3001)<br/>Native SQLite Persistence / ACID Tx / Token Sandbox"]
    QQ_Svc["qq-bridge (:3002)<br/>Two-Way Chat Relay / Throttled Events / Allowlist Approval"]
    BDS_Tools["bds-tools<br/>BDS Auto-Updater / Add-on Inbox Pipeline"]
  end

  subgraph Game_Layer ["Minecraft BDS Instance"]
    Bootstrap["Host Bootstrap Injector"]
    subgraph SAPI_Bundle ["Dynamically Assembled Behavior Pack (sfmc-modules)"]
      ModA["Business Module A (e.g. economy)"]
      ModB["Business Module B (e.g. land)"]
      ModC["Business Module C (e.g. afk)"]
    end
  end

  Client_Layer <==> Companion_Layer
  Companion_Layer <== Authenticated REST / IPC ==> Game_Layer
Loading

✨ Key Features & Architectural Highlights

  • 🗄️ Industrial-Grade Data Persistence (ACID SQLite)
    Say goodbye to fragile Dynamic Properties with storage limits and world-corruption risks. The local db-server provides transaction-protected (ACID) SQLite storage with WAL high-concurrency writing and reliable cold backup workflows.
  • 🧩 Dynamic Behavior Pack Assembly Pipeline
    At server startup or reload, the platform inspects module-lock.json and uses esbuild to compile all enabled TypeScript modules into a single, unified native behavior pack, eradicating UUID collisions and dependency chaos.
  • 🛡️ Microkernel Sandbox & Strongly-Typed RPC Contracts
    Modules explicitly declare database tables and required service dependencies in manifest.json. The platform issues scope-restricted Bearer Tokens to enforce data isolation, while cross-module communication relies on typed RPC services rather than global namespace pollution.
  • ⚡ Sub-Second Hot-Reload Development Workflow
    With the official "SFMC Module" VS Code extension, editing module source code immediately triggers incremental bundling and in-game /reload, eliminating tedious server restarts and player disconnections.
  • 🤖 Turnkey Multi-Platform Social Bridge (QQ Bridge)
    Native support for Tencent QQ Open Platform official bots and OneBot 11 (LLBot), featuring in-group server status queries, rich interactive card actions, bi-directional chat relay, real-time event push, and asynchronous allowlist approval.
  • 📦 Add-on Inbox Pipeline
    Drop .mcpack or .mcaddon files into the packs/ inbox for automated parsing and deployment, complete with version conflict detection, CurseForge remote updates, and resource pack cache busting (packs bump).

🚀 Quick Start

Track A: Server Operators (Ready in 3 Minutes)

Ensure Node.js ≥ 22.13.0 is installed (required for native node:sqlite support).

# 1. Install SFMC CLI globally
pnpm add -g @sfmc-bds/sfmc@0.2.2

# 2. Create and enter your server workspace
mkdir my-bedrock-server && cd my-bedrock-server

# 3. Launch the interactive REPL console
sfmc

# 4. Start all companion services and BDS in one command
sfmc> start -all

# 5. Search and install gameplay modules from the official index
sfmc> mod install afk

pnpm v11+ waits 24 hours by default before selecting a newly published version from an unversioned package name. To install on release day, check pnpm view @sfmc-bds/sfmc version and pin that exact version as above.

Track B: Module Authors (Build in 5 Minutes)

You don't need to clone this monorepo! Scaffold your standalone module repository directly:

# 1. Interactively scaffold your author repository
pnpm dlx @sfmc-bds/create-module@latest

# 2. Open the created project in VS Code or Cursor
# 3. Install the official "SFMC Module" extension
# 4. Press Ctrl + Shift + P to execute:
#    - SFMC: Link to SFMC Root   (mount directly into your local testing server)
#    - SFMC: Start Watch         (enable real-time incremental watch & hot-reload)

🗺️ Monorepo Package Map

This repository houses the SFMC core platform and tooling packages, organized with strict microkernel separation:

Package Path npm Distribution Role & Responsibilities
modules/sdk/@sfmc-sdk @sfmc-bds/sdk Core runtime SDK for SAPI & Node services (db / config / service / runtime)
packages/cli @sfmc-bds/cli Server orchestration CLI and interactive REPL console
packages/db-server @sfmc-bds/db-server High-performance SQLite HTTP data hub, transaction engine, and token sandbox
packages/qq-bridge @sfmc-bds/qq-bridge Tencent QQ Official Bot and OneBot 11 two-way communication gateway
packages/bds-tools @sfmc-bds/bds-tools BDS version updater and add-on inbox deployment pipeline
packages/create-module @sfmc-bds/create-module Official module scaffolding engine (pnpm dlx @sfmc-bds/create-module)
packages/devkit @sfmc-bds/devkit Incremental transpiler (esbuild), file watcher, and reload core
packages/sfmc-extension @sfmc-bds/sfmc-extension Official VS Code / Cursor IDE extension ("SFMC Module")
packages/meta @sfmc-bds/sfmc Meta-package aggregator distribution
modules/sdk/@sfmc-eslint-plugin @sfmc-bds/eslint-plugin Platform-tailored ESLint rules (Msg helpers, boundary checks)

🌟 Featured Module Ecosystem

All official modules are published to npm and curated in the Official Module Repository:

Module ID Display Name Features & Highlights
feature-economy Economy System Unified Scoreboard & SQLite currency abstraction with cross-player transfers
feature-land Land Claims 3D visual selection, granular permission controls (break, interact, container), and transfers
feature-teleport Teleport Hub Personal homes, public warps, and inter-player TPA requests across dimensions
feature-auth Authentication Mixed offline/online authentication, auto-login memory, and movement freeze
(platform host) QQ Account Link /c:bind, visitor play-gate, join/leave/death → QQ; absorbed into SDK host like monitoring; retired module ids qq-link / feature-qq-link
feature-afk AFK Detection Smart idle status detection, invulnerability shields, and scheduled rewards

📖 Documentation Hub

Comprehensive architecture guides, API signatures, and developer tutorials are published on our Documentation Site:

  • 📘 User Guide: Service orchestration, configuration reference, module management, and backups.
  • 🛠️ Developer Guide: Author workflow, architecture design, testing strategy, and Manifest contracts.
  • 🔌 API & Protocol Reference: HTTP REST endpoints, dual auth model, RPC discovery, and database transactions.
  • 📚 SDK Type Reference: Complete TypeScript API documentation auto-generated via TypeDoc.

📄 License

The SFMC platform is open-source under the AGPL-3.0 License. Package-specific details can be found in LICENSES.md:

  • Platform & Services (AGPL-3.0): Community improvements are welcomed. Distributing modified versions of the platform or backend services requires making corresponding source code available under the same license.
  • Module Independence (Author Choice): Business modules built with the ISC-licensed @sfmc-bds/sdk are not subject to AGPL copyleft viral effects. Module authors retain full freedom to license their works under any open-source or proprietary commercial terms.