TableFlux logo
TableFlux
Store, library, campaigns
StoreLibraryCampaigns
Back to docs

TableFlux Plugin Authoring Playbook

End-to-end implementation plan for creating a new plugin package from a blank Godot project.

Plugin AuthorsActiveArchitecture

TableFlux Plugin Authoring Playbook

This playbook is for handing work to a developer or AI with enough detail to build a plugin package without additional direction.

#Source of Truth

  • Behavioral and API references are generated from source tags into:
    • plugin-interface-reference.generated.md
    • plugin-interface-reference.generated.json
  • Regenerate references with:
    • tools\generate-plugin-interface-docs.ps1
  • Publish docs to website and SDK mirrors with:
    • tools\sync-tableflux-docs-to-website.bat

#Plugin Family Selection

Pick the plugin family first because folder structure, manifest file names, and registry calls are family-specific.

Current plugin families live under:

  • scripts/gdscript/Plugins/Minigames/
  • scripts/gdscript/Plugins/Rules/
  • scripts/gdscript/Plugins/CharacterGeneration/
  • scripts/gdscript/Plugins/ScriptedEntities/
  • scripts/gdscript/Plugins/TextGeneration/

#Package Discovery System

Package-backed plugins are discovered through subsystem registries and PackageConfigRegistry.

Core discovery references:

  • scripts/gdscript/PackageConfigRegistry.gd
  • scripts/gdscript/Plugins/Rules/Shared/RulesPackageRegistry.gd
  • scripts/gdscript/Plugins/Minigames/Shared/MinigameRegistry.gd

Subsystem package manifest filenames are defined in PackageConfigRegistry.SUBSYSTEM_CONFIG_FILENAMES.

#Minigame Plugin Implementation Plan

#1. Create folder layout

Use plugin ownership layout:

  • scripts/gdscript/Plugins/Minigames/<YourGame>/
  • scenes/ui/plugins/minigames/<your-game>/ (if dedicated scenes are needed)
  • test/scripts/gdscript/Plugins/Minigames/<YourGame>/

#2. Implement minigame contract

Your main script should implement all required IMinigame methods.

Required interface file:

  • scripts/gdscript/IMinigame.gd

Optional action interface when reliable discrete actions are needed:

  • scripts/gdscript/IMinigameActionReceiver.gd

Canvas integration interface:

  • scripts/gdscript/IMinigameCanvas.gd

#3. Wire manager callbacks and invocation APIs

MinigameManager injects manager/canvas/session hooks and drives player/session lifecycle.

Primary manager APIs plugins typically invoke:

  • send_paddle_input(normalized_x)
  • send_minigame_action(action_id, action_value)
  • broadcast_state_sync(session_id, state)
  • report_minigame_scores(score_rows, title)
  • report_minigame_outcome(session_id, outcome)

Implementation source:

  • scripts/gdscript/MinigameManager.gd

#4. Register minigame definition

Minigames are registered by MinigameRegistry using built-in definitions and discovered package manifests.

Registry source:

  • scripts/gdscript/Plugins/Minigames/Shared/MinigameRegistry.gd

#5. Add packaged manifest (if shipping as package)

Create minigame_package.json with at least:

  • game_id (or package_id fallback)
  • display_name (or package_name fallback)
  • script_path

Recommended fields:

  • description
  • category
  • capabilities
  • package_root_name
  • package_tree_path
  • source_kind

Reference example:

  • test/scripts/gdscript/Plugins/Minigames/Racing/minigame_package.json

#6. Validate networking behavior

Required networking model:

  • Host/server authoritative game state.
  • Reliable discrete actions, lightweight movement updates.
  • Regular authoritative state sync + immediate sync for major state changes.
  • Late-join snapshot support.

#Rules Package Implementation Plan

Rules plugins are package-driven scene and behavior overrides resolved through RulesPackageRegistry.

Primary references:

  • scripts/gdscript/Plugins/Rules/Shared/RulesPackageRegistry.gd
  • scripts/gdscript/PackageConfigRegistry.gd

Key rule package extension points:

  • character_creation_scene_path
  • conflict_resolution_scene_path
  • ruleset_kind
  • provided_features fallback map

Feature resolution entry point:

  • resolve_package_screen_feature(package_id, feature_id)

#Deterministic Code Reference Workflow

  1. Add or update [Plugin:*] tags near interface points and extension hooks.
  2. Run tools\generate-plugin-interface-docs.ps1.
  3. Review generated markdown/json outputs.
  4. Run tools\sync-tableflux-docs-to-website.bat to publish docs and manifest.
  5. Run docs validation/build in website repo.

The generator now enforces strict linting:

  • Missing required tag fields fail generation.
  • Duplicate id values fail generation.
  • Invalid required values fail generation.

The generated markdown includes New Plugin Checklists grouped by subsystem from required=true tags. Use plugin-scaffold-templates.generated.md for deterministic subsystem templates listing required IDs and optional extension points.

#Tag Format

Tag syntax used by the generator:

  • ## [Plugin:<Type>] id=<stable-id>; owner=<class-or-module>; kind=<method|interface|registry|schema|path|manifest>; required=<true|false>; subsystem=<name>; phase=<lifecycle-phase>; summary=<text>

Recommended tag types:

  • Contract
  • EntryPoint
  • Invoke
  • Manifest
  • Folder

#Handoff Checklist

  • Plugin files are in correct plugin-owned folders.
  • Required interface methods are implemented.
  • Package manifest and script paths resolve at runtime.
  • Session/network sync behavior is host authoritative.
  • Regression tests exist for lifecycle, sync, and outcomes.
  • [Plugin:*] tags added for all new extension points.
  • Generated reference docs regenerated and synced.