Pocket Chordsmith Godot Addon

Pocket Chordsmith imports web-app JSON into compiled Godot resources, then drives runtime music callbacks through one lightweight conductor node.

Author charts in the Pocket Chordsmith web app:

https://samfa12.itch.io/pocket-chordsmith

Pipeline:

Pocket Chordsmith JSON -> importer/schema migrator -> PCSChartResource -> PocketChordsmithConductor

Runtime rules:

• Gameplay uses PCSChartResource, not full JSON.
• PocketChordsmithConductor owns timing, arrangement position, event cursors, beat/bar/section signals, markers, accents, and transition requests.
• Godot's built-in audio system remains the playback foundation. Use buses, effects, AudioStreamPlayer, AudioStreamSynchronized for stems, and AudioStreamPolyphonic for short accents/stingers.
• The legacy runtime/PocketChordsmithPlayer.gd is retained as an older procedural preview/reference path. It should not become the shipped runtime audio architecture.

Editor workflow:

1. Enable the Pocket Chordsmith addon.
2. Open the Chordsmith main screen.
3. Import a Pocket Chordsmith JSON, paste raw JSON, or paste a PCS1: share code.
4. Inspect the import report, sequence, sections, timeline, and event counts.
5. Optional: click Generate Web Sound Kit to create Pocket Chordsmith-style drum/stinger WAVs and a HYBRID playback profile.
6. Save the compiled chart as .tres or .res.
7. Assign the chart and playback profile to PocketChordsmithConductor in a level or demo scene.

The addon does not require users to bring their own drum WAVs just to get started: the editor can generate a small built-in preview kit. At runtime, audio still uses Godot-native AudioStream playback. For a shipped game, use generated samples, your own licensed drum/stinger samples, rendered stems, or a mix of stems plus event-triggered samples.

Visual track building stays in the web app for now. Godot receives the exported JSON/share code, compiles it to a lightweight PCSChartResource, then uses the conductor for timing, states, markers, cues, and Godot-native audio routing. A future Godot visual editor should build on the compiled chart/section data instead of porting the whole browser app into runtime.

For batch migration, use the editor Compile Folder button or the headless compiler:

godot --headless --path <project> --script res://addons/pocket_chordsmith/tools/compile_pocket_chordsmith_charts.gd -- --source <json-or-folder> --beside-source

The main screen also includes Create Chordsmith Audio Buses. This safely adds missing recommended buses only:

Master
  Music_Master
    Music_Drums
    Music_Bass
    Music_Chords
    Music_Melody
    Music_Stingers
    Music_FX
  SFX
  UI

Existing buses are reused. Existing sends are reported as warnings instead of being overwritten.

Runtime signal example:

@onready var conductor: PocketChordsmithConductor = $PocketChordsmithConductor

func _ready() -> void:
    conductor.accent_hit.connect(_on_accent)
    conductor.section_started.connect(_on_section_started)
    conductor.marker_hit.connect(_on_marker_hit)
    conductor.play()

Native audio extension points live in PCSPlaybackProfile and the conductor:

• stem paths and bus names
• music/accent bus names
• intensity mix targets
• ducking rules
• filter automation maps
• optional native audio router node via native_audio_router_path

Playback backends:

• STEM_SYNC: preferred shipped-game path using rendered stems and Godot playback.
• HYBRID: stems for the main bed plus event-triggered accents or stingers.
• PROCEDURAL_PREVIEW: editor-oriented preview mode, not the default mobile runtime path.

Adaptive music states:

conductor.set_music_state("exploration")
conductor.queue_music_state("combat", PocketChordsmithConductor.TransitionBoundary.NEXT_BAR)
conductor.queue_sequence(["A", "B", "C"], PocketChordsmithConductor.TransitionBoundary.NEXT_SECTION)
conductor.trigger_stinger("victory_hit", "exploration")

States are stored on PCSChartResource.music_states and can map to section, sequence, loop_sections, entry, stinger, and then_return_to. Transitions can wait for immediate, beat, bar, section, loop, or marker boundaries.

Native mix controls:

conductor.set_layer_volume("drums", -6.0)
conductor.mute_layer("melody", true)
conductor.duck_music(true, 0.5)
conductor.lowpass_music(0.75)
conductor.set_bus_effect_amount("Music_Master", "reverb", 0.25)

More docs:

• CHANGELOG.md
• MIGRATION.md
• docs/GETTING_STARTED.md
• docs/LEVEL_INTEGRATION.md
• docs/SHIPPING_CHECKLIST.md
• docs/RELEASE_CANDIDATE.md
• docs/CLI_COMPILE.md
• docs/RUNTIME_BRIDGE.md
• docs/STEM_WORKFLOW.md
• docs/SAMPLE_PREVIEW.md
• docs/UID_CACHE_RECOVERY.md
• SKILL.md for AI-assisted project integration

Release-candidate tools:

godot --headless --path <project> --script res://addons/pocket_chordsmith/tools/validate_pocket_chordsmith_runtime.gd -- --chart <chart.tres> [--profile <profile.tres>] [--report <report.md>]

Godot Asset Library release checklist:

1. Commit all release changes to Git.
2. Copy the full 40-character Git commit hash from the committed revision.
3. Paste that full hash into the Godot Asset Library Download Commit field.
4. Do not use branch names or tags such as main, master, or v1.0.0 for Download Commit.