X-Lifestyle Core

Appearance

X-Lifestyle Core — Integration Guide ​

For anyone integrating a new mod with Core — declaring the dependency, understanding how Core's feature-gate system works and what it means for you as an addon author, and what to do (and not do) with "testing"-state features while you build. This guide deliberately does not cover individual BMFT.* functions, macros, or feature APIs — that's Developer Guide's job. Read this one first if you're new to building on Core; read the developer guide once you're actually calling something specific.

Self-contained, same as the developer guide — this file assumes only that you have Core's own source or a copy of this guide, not a checkout of the xls umbrella repo it's normally developed alongside.

This guide is reviewed on every Core release, not written once and left to rot — see "Keeping this guide honest" at the bottom.

1. Declare Core as a dependency ​

Every X-Lifestyle mod declares Core in its own .meta:

yaml
requiredMods:
  - name: "X-Lifestyle Core"
    loadMyMod: after

loadMyMod: after means your mod loads after Core, so window.BMFT is already populated by the time your own scripts run. This is a real, engine-enforced field — see your mod's own .meta schema reference for the full field shape if you need a version constraint too (and see step 3 below for why you'll want one).

2. Feature gates and testing mode — read this before you build against anything new ​

Core ships new or risky functionality behind window.BMFT.Features, a code-only feature gate (no in-game UI, no player-facing toggle). Each gated feature has a state: "enabled" (live for everyone), "disabled" (off for everyone), or "testing" (in progress, not yet trusted for a real release — live only in a build packaged with Core's own buildMode: "testing" option). Full design: docs/ai/feature-gates.md, if you have access to Core's own repo.

What this means for you as an addon author: a "testing"-state feature is real, working code you can build against today — but it's not live in a normal install of Core. If your addon depends on something still "testing", your addon's own players won't see it working until Core promotes that feature to "enabled" in a real release. Check the feature's own status before you build a release around it.

Enabling testing mode to try a "testing" feature yourself ​

Two sanctioned ways to see a "testing" feature actually running while you develop:

Option A — build Core yourself (safest, recommended):

  1. Clone Core's own repo: gitgud.io/binarymisfit/x-lifestyle-core.
  2. From inside that clone, run node .release/package.js --testing. This is Core's own packaging script (lives in its .release/ directory), given the --testing flag.
  3. It produces a .xcl file in dist/ with window.BMFT_BUILD_MODE = "testing" baked into a generated file inside the archive. Install that .xcl in your own dev environment instead of a normal release build.

This is the safer option because the testing signal only ever exists inside that one built archive — there's nothing sitting in a source file you could later forget to remove.

Option B — a quick local toggle, for a fast one-off session:

  1. Open your browser's dev console while the game is running (or write a throwaway script you only ever load in your own local dev environment, never committed anywhere).
  2. Run: window.BMFT_BUILD_MODE = "testing";
  3. Continue playing, or reload — every "testing"-state feature is now live for this session.

Never commit or ship that second approach. window.BMFT_BUILD_MODE is a plain global — nothing in Core stops your own mod's script from setting it, and nothing about it looks unusual in your own code. If a script that sets it ends up in your addon's published package, every player who installs your addon gets every "testing"-state feature in whatever version of Core they have turned on — not just for you, for them too, and not just the feature you were testing, all of them. This is a real leak path, not a hypothetical: before publishing, grep your own mod's source for BMFT_BUILD_MODE and confirm nothing sets it in anything that ships.

The safety net, and why it isn't a substitute for the checklist above ​

If a leak like that ships anyway, Core has a kill switch that can reach it: forceDisabled on a FLAGS entry overrides everything — state, build mode, your addon's script forcing window.BMFT_BUILD_MODE — unconditionally. Core's maintainers can ship a patch flipping the affected flag's forceDisabled to true, and once players update to that patched Core, the leaked feature stops working again, regardless of what your addon's own script still does.

This only helps once affected installs actually update to the patched Core — it's a correction mechanism, not a live remote kill switch. If your addon pins an old requiredMods version constraint, or your players never update, the leak persists for them until they do. Treat forceDisabled as Core's emergency brake for a mistake that already shipped, not as a reason to skip checking your own addon before you publish it.

3. Core changes, and what that means for your own releases ​

When Core changes in a way that affects a feature your addon depends on, your addon needs its own new release declaring the updated requiredMods constraint — this doesn't happen automatically just because Core published a new version. If you're maintaining an addon long-term, watch Core's own CHANGELOG.md for changes to anything you depend on, not just version numbers.

4. The reliability guarantee ​

Anything Core documents in DEVELOPER_GUIDE.md for you to call degrades gracefully when its owning feature is off — it never throws and never stops existing. When a feature is disabled or still "testing", a documented function falls back to whatever the base game's own standard behavior would be, not an error. You can call anything Core documents without defensively checking "is this feature currently on" first — that check already happened inside Core. This guarantee is what makes depending on a still-gated feature safe at all: your own content never breaks just because Core flips a flag.

Keeping this guide honest ​

This guide only covers integration mechanics that are actually shipped, not planned changes to how they'll work — check Core's own CHANGELOG.md for anything more recent than what's described here. If you find a section here that doesn't match what the code actually does, that's a real bug in this guide — report it the same way you'd report any other bug in Core.

For Core's own maintainers: this file is reviewed as part of every release, not written once and left to drift — see this repo's own CLAUDE.md for the standing rule.

Zlib Licensed

BinaryMisfit