campaignKit.package
- .metadata17 B
- CampaignHost.component
- README.md6.1 KB
- api.module
- director.module
- events.module
- guides
- looks.module
- maps.module
- medals.module
- package.yaml1.1 KB
- progress.module
- runners.module
- sounds
- sounds.module
- story.module
- tests
This package holds more than this page lists. See all of its files in its world.
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 atmap.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) andlist. 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 returnsbest.text(e.g."20 lives left") orbest.score, which show in its place. Withoutmap.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;
menuLookturns the look plus your title painting into a matching menusKit look,dialogueLookinto 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.extrafor 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 = nilplays platformer3dKit levels (Level_<id>entities fromP3D.level); a table{ start, stop, restart, best?, startPoint? }plays anything else, withCampaign.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
| Part | What it does |
|---|---|
api | front door: start, status, on, go, restart, finished, setMapStyle, setSoundSet, sting, catalogue |
director | the flow, keys, pause, results bar, progress saving |
maps | the four level-select styles |
looks, medals | look tokens and screen helpers; medal displays |
sounds, story | music, campaign sounds, move sounds; story beats and NPC |
progress, runners, events | per-player progress; platformer3dKit / custom runners; local signals |
CampaignHost | the per-machine host component (spawned for you) |
sounds/ | storybook, cartoon and sci-fi clips (retro comes from chipSfx) |
tests/campaignKitTests | tests 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.