Log inGet started
World

Campaign Trail: Title Screen, Level Select, Story Beats and Results for Level-Based Games

README.md

campaignKit

The game around your levels, from one config call. A level-based game (a platformer, a racer, a puzzle game) needs the same shell around its levels every time: a title screen, a level select that unlocks levels and shows best times and medals, a story beat before and after each level, a results screen with Next / Retry / back to the map, a pause menu, an ending and credits, music for each screen and level, and sounds for the player's jumps, landings, checkpoints and falls. campaignKit is that shell. It wires together kits that already do each part (menusKit, saveKit, dialogueKit, soundstage, chipSfx) and runs platformer3dKit levels out of the box.

local Campaign = require("campaignKit.api")
-- in play, from any component's update (calling it again does nothing):
Campaign.start({
  id = "myGame", title = "Sky Hop", subtitle = "Five islands above the clouds",
  levels = {
    { id = "isle1", title = "First Hop", subtitle = "Dawn", time = "dawn", par = 45 },
    { id = "isle2", title = "Windy Steps", subtitle = "Midday", time = "midday", par = 60 },
  },
  map = { style = "lanterns" },          -- storybook | parchment | lanterns | list
  look = "cartoon",                      -- parchment | cartoon | minimal | pixel | scifi | night
  medal = "stars",                       -- disc | stars | ribbon | grade
  sounds = { set = "cartoon", music = { title = titleClip, select = mapClip, levels = { isle1 = isleClip } } },
  story = { conversations = myConversations, before = "intro_{level}", after = "outro_{level}", finale = "ending" },
  finale = { play = playMyEnding, credits = { { title = "Made by", names = { "You" } } } },
})

What a world gets

  • Flow, per player: menusKit title (Play, Continue, Settings, Credits) -> level select -> story beat (dialogueKit) -> the level -> results + after-words -> Next (with the next level's beat) / Retry / map. After the last level: your finale hook (finale.play(done)), the finale words, credits, back to the map.
  • Level select, four styles, one setting (map.style): storybook (your painted illustration, map.art, with glowing waystones at map.spots), parchment (an inked map on old paper, the walked trail in red ink, a compass rose), lanterns (a string of lanterns across the night that light as levels clear) and list. Each shows lock / best / medal per level and a card for the chosen level (par, best, coins, medal, Play). The best is the run's time; a runner whose levels have no time returns best.text (e.g. "20 lives left") or best.score, which show in its place. Without map.spots, the stops zig-zag between two rows (three past seven levels), clear of the level card, so no name tag covers a stop. Arrows / WASD / Enter / Esc, mouse and touch.
  • Looks: six built-in looks for every campaign screen, overridable token by token; menuLook turns the look plus your title painting into a matching menusKit look, dialogueLook into a matching dialogueKit style.
  • Medals: disc, stars, ribbon or grade badge (medal), tiers renamable (medals).
  • Sound: music per screen and per level (soundstage, local to each player), nine campaign sounds in four sets (sounds.set: storybook, cartoon, retro 8-bit from chipSfx, sci-fi), sounds.extra for your own stingers, jump / land read from the player's CharacterController, checkpoint / death from the runner.
  • Progress: saveKit per-player profile, one unlock per level (save.unlockPrefix), your own unlocks (save.unlocks), coins stat, finale seen.
  • Multiplayer: everything is this machine's player only: screens, music, pause, story NPC and progress. Two players in one level never drive each other's screens.
  • Runners: runner = nil plays platformer3dKit levels (Level_<id> entities from P3D.level); a table { start, stop, restart, best?, startPoint? } plays anything else, with Campaign.finished(id, { time, tier, coins, totalCoins }) when a run ends.

Config fields

id, title, subtitle, version, levels (each { id, title, subtitle?, par?, time?, swatch?, next? }), runner, look, menuLook ({ name, art, aspect, ornament, ornamentLit, glowAt, base } or a menusKit look name), menuLayout, dialogueLook ({ name, style = { dialogueKit fields } }), map ({ style, art, aspect, spots, dim, artOpacity }), medal, medals, sounds ({ set, music, extra, volume, feedback }), story ({ conversations, before, after, finale, npc = { model, entity, light }, style, voice }), save ({ namespace, unlockPrefix, unlocks, xp, curve, theme }), finale ({ play(done), after, auto, credits, creditsTitle, thanks }), credits, text (every word on the screens: play, map, ending, heading, subheading, hint, back, lockedHint, unlocked, ...), hooks (boot, title, select, level(id), results(id), state(s, id)), showTitle, livesHud, startPoint(id), coins (false drops the Coins row from the level card, for a game without coins).

Parts

PartWhat it does
apifront door: start, status, on, go, restart, finished, setMapStyle, setSoundSet, sting, catalogue
directorthe flow, keys, pause, results bar, progress saving
mapsthe four level-select styles
looks, medalslook tokens and screen helpers; medal displays
sounds, storymusic, campaign sounds, move sounds; story beats and NPC
progress, runners, eventsper-player progress; platformer3dKit / custom runners; local signals
CampaignHostthe per-machine host component (spawned for you)
sounds/storybook, cartoon and sci-fi clips (retro comes from chipSfx)
tests/campaignKitTeststests for progress, maps, looks, medals, sounds, story, runners and the flow
guides/how to add a title screen, level select map, story and results to a level-based game

The kit world, Campaign Trail, has a showcase scene with three tiny levels; press 1-4 on its map to swap the map style live.