Description

Area Music 🔗

Cuboid area playlists for Luanti / Minetest. Music lives in the world folder (not in the mod). The server pushes .ogg files to clients with core.dynamic_add_media.

Features: fade-out, loop fade-in, auto loop/shuffle playlists via jukebox, wand, areas manager tab / /am_gui, chat commands.

Apache-2.0. No music is bundled.

Authorship / AI: This mod’s code was generated by Grok Bot, supervised by Wilbur Jaywright (author credit on ContentDB / in mod.conf: Grok Bot supervised by Wilbur Jaywright).

Install 🔗

1. Copy the area_music folder into your game’s or world’s mods/ directory (or unpack the zip so you get mods/area_music/).

2. Enable the mod for the world.

3. Create the music folder (the mod also creates it on load):

   <worldpath>/area_music/
   

4. Drop .ogg files there. The track name is the file name without .ogg (e.g. forest_day.ogg → track forest_day).

5. Restart the server (or use /am_reload / Refresh tracks after adding files while running).

Track filenames (engine limit) 🔗

Luanti only accepts media names with these characters: a-z A-Z 0-9 _ . -. Spaces and other punctuation are rejected by the engine (dynamic_add_media / sound_play) — this is not an area_music formspec bug. Prefer forest_day.ogg over forest day.ogg.

On scan / /am_reload, files with invalid names are skipped with a clear server warning. Rename them on disk, then refresh.

Requirements: Luanti / Minetest 5.5+ recommended (for dynamic_add_media with to_player). Optional: sfinv and/or unified_inventory for an Area Music inventory tab (server priv). /am_gui always works as a fallback. With Unified Inventory, look for the jukebox icon in the bottom button row.

Creative inventory 🔗

Area Music Jukebox and Area Music Wand are normal registered items — they appear in the creative inventory (search “Area Music”). You can also obtain them with /am_jukebox / /am_wand.

Quick start 🔗

All admin actions need the server privilege.

1. /am_wand — get the wand. Left-click = pos1, right-click = pos2 (or use /am_pos1 / /am_pos2).
2. Create an area: /am_add my_cave (optional priority: /am_add my_cave 10)
   or open /am_gui and press + Create.
3. Get a jukebox from creative inventory (or craft 3×3 wood, or /am_jukebox) — place it inside the area.
4. Right-click the jukebox: add/remove tracks, set gap (seconds), and optionally Fade in. Mode is automatic (1=loop, 2+=shuffle).
5. Walk in — music plays for you only (to_player). Leaving fades out. Spawning already inside an area also starts music.

Playlists 🔗

Each area has:

• List of tracks that may play
• "Fade-in" toggle
• "Gap" in seconds

For modders, the technical references for these parameters are:

playlist.tracks   — list of basenames (no .ogg)
playlist.mode     — auto: "loop" if ≤1 track, "shuffle" if 2+
playlist.gap      — seconds after entering, and between shuffle tracks (0 = none)
playlist.fade_in  — per-jukebox toggle (default false); see Fade
priority          — area overlap ranking (`/am_add` / `/am_priority`)

Track durations: On load and /am_reload, each world/area_music/*.ogg is measured once (pure Lua Ogg/Vorbis parse; ffprobe on PATH as fallback). Lengths live in an in-memory table (also written to world/area_music_track_lengths.dat) and are not re-parsed when a track plays. Shuffle uses that cached length with monotonic timing from play start. If a file cannot be measured, area_music.default_track_length (default 180) is used and a warning is logged.

Jukebox 🔗

• Node: area_music:jukebox
• On place / punch / periodic timer: binds to the smallest-volume cuboid area that contains the node and has no other jukebox (jukebox_pos free or already this node).
• Linked → normal texture + right-click GUI (add/remove tracks, gap, fade-in toggle; mode is automatic).
• Not inside a valid unbound area → swaps to area_music:jukebox_broken (red/cracked look); right-click explains why.
• Digging unlinks the jukebox, clears that area’s playlist, and stops music for players inside.
• Editing the playlist (add/remove/gap) restarts playback as if those players just entered the area (enter gap + reshuffle).

Wand 🔗

• Item: area_music:wand via /am_wand
• Punch (left) = pos1; place/right-click = pos2
• Requires server priv; reuses the visual corner markers

Areas manager (inventory tab / /am_gui) 🔗

• Areas only: create / delete / list / detail (corners, priority, jukebox link, track count), plus Refresh tracks (same as /am_reload).
• Not for playlists — edit tracks and gap only at the jukebox.
• With sfinv or unified_inventory, the manager is inline in the Area Music tab (no “open manager” button).
• /am_gui opens the same UI as a standalone formspec. Chat commands remain full substitutes.
• Create is disabled when pos1/pos2 unset or corners already match an existing area.
• Name dialog: Enter or Create confirms; Cancel dismisses.

Commands 🔗

Overlap rule 🔗

When several areas contain the player:

1. Higher priority wins (default 0; set via /am_add or /am_priority).
2. If priorities are equal, the smaller volume wins.

Volume is the inclusive block count between the two corners (WorldEdit-style).

Fade 🔗

• Fade-in is a per-jukebox toggle (playlist.fade_in, default off). Duration is area_music.fade_duration (default 2.0 s). When on: fade-in only as the player enters the area (1-track first play, or shuffle’s first track). Later loop restarts and later shuffle picks start at full volume. When off: every start is full volume.
• Fade-out on leave, area-switch, or shuffle track end is always on: sound_fade to 0, then sound_stop. In-flight fades are tracked so a new play does not fight an old fade; leaveplayer invalidates state.

Without sound_fade, fade-out is a delayed stop and fade-in is skipped (starts at full gain).

Multiplayer 🔗

• Playback is per-client (sound_play with to_player).
• On join and /am_reload, the server pushes each world .ogg via dynamic_add_media.
• Areas are stored in <worldpath>/area_music_areas.dat.

Settings 🔗

These knobs live in settingtypes.txt / minetest.conf. Fade behavior is under Fade; durations and gain are set here.

area_music.check_interval = 1.0
area_music.default_gain = 0.5
area_music.fade_duration = 2.0
area_music.default_track_length = 180   # fallback only if duration unreadable

Layout 🔗

area_music/                      ← this mod (no .ogg here)
  mod.conf
  init.lua
  storage.lua
  media.lua
  playback.lua
  markers.lua
  jukebox.lua
  wand.lua
  gui.lua
  commands.lua
  LICENSE
  README.md
  settingtypes.txt
  textures/
    area_music_pos1.png
    area_music_pos2.png
    area_music_jukebox.png
    area_music_jukebox_broken.png
    area_music_wand.png

<worldpath>/
  area_music/                    ← put your .ogg files here
  area_music_areas.dat           ← auto-saved area list

Notes 🔗

• Prefer Ogg Vorbis. For loop mode, use files designed to tile cleanly.
• No spaces in filenames (Luanti media charset). Underscores/hyphens are fine.
• /am_reload / Refresh tracks also removes playlist entries whose files disappeared from disk (logged per area).
• Durations refresh only on load / /am_reload (or when the jukebox/list rescans).
• default_track_length is only a fallback when a file cannot be parsed.
• /am_reload after adding new files is the usual workflow.
• Not published to ContentDB by default; distribute the zip for local/server install.

License 🔗

Apache License 2.0 — see LICENSE. Copyright 2026 Wilbur Jaywright, supervising generation by Grok Bot.