Getting started

Install SFMC locally and bring your server online.

This page is for operators and module authors. After reading it, you should be able to:

Complete installation and first-time setup
Manage services and modules with common commands
Tell modules apart from add-ons, and know where development workflow begins

Details live in later chapters; see Command reference for a quick lookup.

System requirements

Item	Requirement
OS	Windows 10 / 11 (primary support today)
Node.js	22.13 or newer
Disk	Space for BDS, backups, and modules

Quick start

Global pnpm

monorepo

pnpm add -g @sfmc-bds/[email protected]
mkdir my-server && cd my-server
sfmc

pnpm v11+ waits 24 hours by default before selecting a newly published version from an unversioned package name. On release day, use pnpm view @sfmc-bds/sfmc version and install that exact version as shown above. Use @beta only to opt into prereleases.

Note

This installs the stable latest release. Add @beta only when you want a prerelease. Data defaults to the current directory; set SFMC_ROOT to use another root.
Build the monorepo once before first use.
Type help in the console for available commands.
For module development, install the SFMC Module extension (test / Watch); see Module authoring.

First run and daily use

The first run opens the setup wizard: pick BDS, data directory, and optional LLBot. After that, the workspace looks roughly like:

{workspace}/
├── {BDS}/
├── configs/
├── data/
├── packs/
└── modules/

sfmc> start -all
sfmc> status

Services start in order db → qq → llbot → bds. Before BDS starts, the module behavior pack is checked; if it is out of date, it is rebuilt first. A failed build blocks the game process.

Command	Purpose
`start db\|qq\|bds\|-all`	Start
`stop` / `restart`	Stop / restart
`mod list`	Installed modules
`mod enable <id>`	Enable a module

Important

After editing configs/*.json or a module's sapi/manifest.json, restart BDS.
Configs and manifests are not hot-reloaded; during development use the SFMC Module extension Watch, or on the server run mod reload.

See Service management for services, logs, and load gates. See Configuration for config files.

Modules

A module is an SFMC business feature package (installed with mod).
An add-on is a third-party behavior or resource pack installed into the world (managed with packs / addon). Do not mix the two command families.

Install existing modules

Develop your own module

sfmc> mod search
sfmc> mod install afk
sfmc> mod enable afk
sfmc> mod reload

Create with pnpm dlx @sfmc-bds/create-module@latest:

cd my-feature && pnpm install && pnpm run typecheck

Link into your SFMC workspace (module short id required). Authors use extension Link / Watch; on the server:

sfmc mod install my-feature --from dir:<absolute-path-to-author-repo> --link
sfmc mod enable my-feature
sfmc mod reload

Layer	Rule	Example
Install id	Short kebab-case name	`my-feature`
manifest / descriptor	`feature-<id>`	`feature-my-feature`
npm (community)	`@<user>/sfmc-module-<id>`	`@alice/sfmc-module-my-feature`

Enable/disable, behavior pack assembly, and reload are covered in Modules. Full author workflow: Module authoring.

Common issues

Symptom	Check first
`/api/health` unreachable	Is db running? Node.js ≥ 22.13?
Module commands do nothing	Enabled? Restarted BDS after changes?
Module code syntax / type error	Run `pnpm run typecheck` or `pnpm run lint`. See Testing & Debugging

Next steps

Chapter	Contents
Service management	Start/stop, logs, load gate
Configuration	`configs/` and reload behavior
Modules	Install, enable, behavior pack
Add-ons	Third-party behavior / resource packs
QQ bridge	Group ↔ server bridge
Command reference	Command cheat sheet
Backup and upgrade	BDS updates and backups
Troubleshooting	Symptoms and fixes

#Getting started

#System requirements

#Quick start

#First run and daily use

#Modules

#Common issues

#Next steps