Skip to content

Musical Cantrip System

Overview

The Musical Cantrip System is an elemental magic system driven by real music performance. It links in-game cantrip casting to musical input, translating performed music into elemental magical effects.

Gameplay Goals

  • Learn music through play — Players internalize tempo, intervals, and rhythm by casting cantrips rather than through abstract drills.
  • Elemental discovery — Each element is unlocked by mastering a specific tempo range on the Looper, rewarding steady timekeeping.
  • Progressive complexity — Basic cantrips require only a correct BPM; advanced cantrips layer in specific melodic intervals and rhythm patterns.

Design Philosophy

The system follows three principles:

  1. Music first, magic second — Every magical effect maps to a real musical concept (tempo, interval, rhythm). The magic is a reward for genuine musical performance.
  2. Feel over precision — BPM ranges (not exact values) define elements, so players develop an intuitive sense of tempo rather than chasing a number.
  3. Paired opposites — Each element has complementary cantrip pairs (e.g., Spark/Snuff, Dampen/Dry) that reinforce the idea of musical balance.

Architecture

The system spans multiple repositories:

Repository Path Purpose
spyder src/cantrip_bridge/*.py Bridge layer connecting music input to cantrip logic
mud-onboarding world/musical_elements.py Defines the elemental music mappings used in the game world
mud-onboarding typeclasses/cantrips/*.py Typeclass definitions for individual cantrip objects
ios Sources/**/Cantrip*.swift iOS client cantrip data model and preset generation
TheSmithy docs/features/cantrips/ Server-side implementation summaries

Data Flow

Player performs music on Looper
        |
        v
  iOS audio engine detects BPM + intervals
        |
        v
  Element resolved from BPM range (see table below)
        |
        v
  Cantrip matched by element + interval pattern
        |
        v
  Cantrip Bridge sends invocation to game server
        |
        v
  Typeclass executes magical effect in the game world

Key Concepts

  • Cantrip Bridge — The intermediary that translates music performance data into cantrip invocations.
  • Musical Elements — The mapping between musical properties (tempo, pitch intervals) and elemental types.
  • Cantrip Typeclasses — The object definitions that determine how each cantrip behaves once triggered.
  • Melody Interval — A specific pitch relationship (e.g., perfect fifth) that distinguishes one cantrip from another within the same element.

BPM-to-Element Reference

Element BPM Range Center BPM Known Cantrips Key Intervals
Earth 75 75 Mend, Crack, Restore Perfect fifth (ascending/descending), perfect fourth
Water 80-89 85 Dampen, Dry —
Fire 100-109 105 Spark, Snuff, Flicker —
Wind 110-120 115 Stir, Still, Whisper —

Element Details

Earth (75 BPM)

Earth cantrips use a fixed tempo of 75 BPM and are differentiated by perfect fifth intervals:

  • Mend — Ascending perfect fifth. Repairs and restores earth-based structures.
  • Crack — Descending perfect fifth. Fractures or splits earth-based materials.
  • Restore (advanced) — Combines perfect fourth and fifth intervals. Performs deep structural restoration of the Forge's earth foundation. Requires beat/rhythm mastery beyond basic cantrips.

Water (80-89 BPM)

  • Dampen — Adds moisture, saturates materials, or creates humidity.
  • Dry — Removes moisture, desiccates materials, or reduces humidity.

Fire (100-109 BPM)

  • Spark — Ignites materials, creates flame, kindles heat sources.
  • Snuff — Extinguishes flames, removes heat, suppresses combustion.
  • Flicker — Creates a rhythmic flame that acts as a visual metronome and communication beacon.

Wind (110-120 BPM)

  • Stir (110-119 BPM) — Creates wind movement, generates wind, circulates atmosphere.
  • Still (110-119 BPM) — Calms wind movement, creates stillness.
  • Whisper (120 BPM) — Carries voice or subtle messages on the wind.

Usage

Players interact with the cantrip system through the Looper instrument:

  1. Set tempo — Tap or play at the target BPM range to select an element.
  2. Play interval — Perform the required melodic interval (where applicable) to select the specific cantrip.
  3. Sustain — Maintain the performance to complete the casting.

Use the listen command in-game to perceive a room's elemental and musical properties, which can hint at which cantrips are effective.

Configuration

Cantrip detection thresholds and element mappings are defined in:

  • iOS client: MagicElement enum and CantripPresetGenerator handle BPM range detection and preset creation.
  • Game server: world/musical_elements.py defines the server-side element mappings and can be adjusted by admins with setelemental and settime commands.

Implementation References

Document Repository Description
EARTH_CANTRIPS_IMPLEMENTATION_SUMMARY.md TheSmithy Earth cantrip integration, Restore system, and music magic fixes
CANTRIP_SYSTEM.md ios iOS data model, preset generation, and cantrip creation guide
cantrip-builder.md ios Claude agent specialized for building new cantrips
BASE_CANTRIPS_IMPLEMENTATION.md ios Implementation plan for the 8 base cantrips in CantripsView