Compatibility, diagnostics and release
How to tell which contract you are building against, what BusinessBridge does on a game build it cannot verify, and what its diagnostics give you as a developer.
Contract and API version
Two values, and they answer different questions:
| Value | What it tells you |
|---|---|
BusinessBridgeApi.Version |
The build of BusinessBridge that is running. Changes for any release, including fixes that do not affect you. |
BusinessBridgeApi.ContractStage |
The shape of the contract. Changes only when the shape of
AiBusinessRegistration changes. This is the one to gate on. |
The current stage is beta-2. Refuse to register against a stage you do not know:
if (BusinessBridgeApi.ContractStage != "beta-2") { /* warn and skip */ }That is better than trying anyway: a changed contract means fields you are not setting, and failing loudly in your own log beats an AI that quietly never opens your business.
beta-1 → beta-2
beta-2 added LayoutContents, so layouts can be handed over in memory
instead of as files on disk. The change is additive: a provider written against
beta-1 needs no edit, because it only ever set LayoutFiles and the new
list simply starts empty. The LayoutFiles path is unchanged and still supported, and
both transports go through the same validation and registration. A provider that uses
LayoutContents needs BusinessBridge at beta-2 or later, which is what the
check above is for.
Game build compatibility
The supported game build is Big Ambitions Build 3680 (Patch 2). On a build where the game's AI template cache cannot be verified, BusinessBridge stays inactive: it rejects every registration with a clear message, shows the player a “needs an update” notification, and never touches the game's own AI.
Your registration will come back with Accepted = false and
the AI template cache does not match this game build. That is the designed behaviour
after a game patch, not a bug in your integration — and your own business type keeps working for
the player throughout.
Diagnostics you can rely on
Every registration decision goes to BusinessBridge's own log and into any support bundle the player creates, so you can diagnose a creator problem from a player's report without asking them for Player.log. In a bundle:
| File | What is in it for you |
|---|---|
registrations.json |
Every registration: provider id, business type, layout name, layout sizes, donor type, each template with its active flag, and the validation messages. |
cache-state.json |
Whether the cache adapter is available, how many templates are live, how many are BusinessBridge's, whether the live cache still holds everything that was applied, plus layouts owned and bridged businesses in the world. |
environment.json |
BusinessBridge version, contract stage, game version and build, Unity version, OS, and the mods that were loaded. |
recent-events.jsonl |
The last few hundred BusinessBridge events, with levels. |
businessbridge.log |
The run's own log, anonymised. |
Bundles are anonymised as they are written and re-scanned before they are zipped, so asking a player for one is a reasonable thing to do. The player-facing bundle instructions explain how they create one — send them that link rather than explaining it yourself.
Deliberately not in this contract
These are real ideas, not commitments, and none of them blocks the beta. Do not build against them yet:
- Custom logo shapes — a bridged AI business borrows a shape from the game's own set. Feasible, investigated, not implemented.
- AI Store Designer — generating layouts instead of shipping them.
- Automatic layout generation from a player-built store.
- Third-party adapters — anything that registers on another mod's behalf.
- SmartSuite-specific compatibility.
- Rival defense with custom types — blocked until a provider can supply every special-rival building size.
Which building sizes are available is decided by each provider mod, not by BusinessBridge. It imposes no list and never substitutes one size for another: a size you do not supply a layout for is a building the AI simply cannot use for your business type.
When you report an integration problem
Developer tickets use the same support system as player reports, with the audience set to Mod developer / creator. That switches the form to ask for the things that actually help here: your project name, which part of the integration is failing, the contract stage you build against, and a repository or gist if you have one.
Include the RegistrationResult messages. They name every decision BusinessBridge
made, and they are usually the whole answer.