Modules and administration

The PostgreSQL catalog contains modules, module releases, selectable Godot versions, and compatibility lists. No module manifest file needs to be edited.

Administrator access

Legacy deployments seed an administrator from GBB_ADMIN_BOOTSTRAP_TOKEN only when the token table is empty. Use it to create a regular credential, then revoke the bootstrap token using its actual database ID. New tokens are shown once and stored as hashes; lost tokens must be replaced. See the token API.

Anonymous deployments use Authelia. Ingress authenticates administrators and supplies identity headers; the API checks the configured administrator group. Token creation/revocation and legacy token-session endpoints return 410 in this mode, and bootstrap seeding is skipped. See Authelia administration.

The admin UI provides engine versions, modules, compatibility, audit records, and abuse-ban management. Token management applies to legacy mode.

Register a module

A module repository contains a Godot engine module with SCsub, config.py, and its sources. Register the repository, then add at least one release. For a legacy local development server:

curl --fail-with-body http://localhost:8080/api/v1/admin/modules \
  -H "Authorization: Bearer $GBB_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"example_module","endpoint":"https://git.example.com/team/example_module.git","path":"modules/example_module","description":"Example engine module"}'

curl --fail-with-body http://localhost:8080/api/v1/admin/modules/example_module/versions \
  -H "Authorization: Bearer $GBB_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"version":"v1.0.0","ref":"v1.0.0","min_godot_major":4,"min_godot_minor":4,"requires":[]}'

Replace the example repository with one the service can clone. GBB_ADMIN_TOKEN must hold an issued admin credential.

Names must match ^[a-z][a-z0-9_]{0,63}$. The default destination is modules/<name>; custom paths must remain relative and cannot traverse upward. Prefer immutable commit refs or stable release tags over moving branches. requires names dependencies for that release, not for all releases of the module.

Publish engine versions and compatibility

Record the engine's display name, Git ref, explicit major/minor, optional repository override, and default-selection flag. Forks need correct major/minor values even when their ref is not a version string.

Compatibility lists are keyed by Godot major/minor. Initial generation selects each module's newest eligible release. Later module releases update the newest engine line; older lists remain frozen. Administrative overrides survive ordinary regeneration. Engine rows on the same major/minor share compatibility, even when they point to different forks, so validate fork compatibility before publishing.

The public catalog is what users can select. Check it after edits, test representative module combinations, and confirm dependencies resolve. An eligible version number is not proof that a module compiles.

See module field reference, compatibility administration, and immutable admission snapshots for the full contracts.