MiniGame

Minigame framework: 26 game modes, arenas, lobby menus, parkour, records and quest integration.

Privatev0.1.0Combat & mobs

RequiresTypeWriter0.9.0-beta-177 (BTC build)GUIQuestRegionMiniPlaceholdersoptional

Built for the BornToCraft network. This extension is documented for reference and is not distributed.

Support

Overview

MiniGame is a single framework that runs many kinds of minigames from TypeWriter entries. You describe an arena in the web panel: the game mode, the lobby and game spawns, player limits, teams, kit, rounds and messages. Players then join through action entries and menus. The extension handles the lobby, the ready check, the countdown, the game itself, the podium and the cleanup.

Every game runs through the same phase sequence: Lobby, Countdown, Playing, Ending, Cleanup. Each running game owns one context that stores its players, teams, scores and state, so rounds, teams and scoreboards behave the same way in every mode. Inventories are saved before the game and restored afterwards. Player changes use region-safe scheduling, so the extension runs on Paper and Folia.

Results are kept in artifacts (wins, scores, best times, rankings) and are exposed to the rest of your server through quest objectives, facts, triggers and placeholders. Parkour, which used to be a separate extension, is now one of the game modes. This extension is documented for reference and runs on the BTC build of TypeWriter.

Features

• 26 game modes — PvP, parkour and movement, survival, strategy, party and arcade modes, all selected with the gameType field of an arena.
• Phase engine — lobby, countdown, playing, ending and cleanup, with a ready check, minimum players, late join and spectators.
• Teams — NONE, SOLO, RED_BLUE or custom teams with your own names, chosen from the lobby menu or auto-balanced.
• Rounds and power-ups — optional rounds that revive players between rounds, and timed power-up drops for the rule-based modes.
• Parkour — start points, ordered checkpoints and end points with particles, fail actions, timers and personal and arena records.
• Dedicated arenas — extra configuration entries for parkour, Dé à Coudre and archery.
• Menus — game browser, arena selection, lobby, team selection, statistics and results menus.
• Persistence — wins, losses, scores, best times and top times stored in artifacts, saved asynchronously.
• Quest integration — a completion objective and fact, plus triggers for game start, end, join, elimination, round start and records.
• Scoreboard and messages — configurable scoreboard lines and join, leave, elimination and win messages with game placeholders.

Installation

1. Run the BTC build of TypeWriter (BTC Core, Paper or Folia).
2. Install the extensions MiniGame depends on: the BTC GUI extension (all menus use it), Quest and Region.
3. Put the MiniGame JAR in plugins/Typewriter/extensions/ and restart the server.
4. Install MiniPlaceholders if you want the <minigame_...> placeholders outside the scoreboard. They are published through the BTC MiniPlaceholders bridge, not PlaceholderAPI.
5. Build the arenas in the world, create a protection region where an entry asks for one (for example the pool of a Dé à Coudre arena), then configure the entries in the web panel.

Getting started

This walkthrough sets up a Spleef arena with persistent statistics.

1. In the TypeWriter web panel, open a manifest page and add a Wins statistics artifact. Give it an artifactId, for example spleef_wins.
2. On the same page add a Minigame Arena entry. Set gameType to SPLEEF, then lobbySpawn, gameSpawn, spectatorSpawn and endTeleport with the position picker.
3. Set minPlayers and maxPlayers, autoStartCountdown (seconds before the game starts) and maxGameDuration (seconds).
4. Enable useRounds and set maxRounds if you want several rounds (players are revived and replaced at gameSpawn each round). Add items to kitItems and keep giveKit on.
5. Link winStatArtifact to the artifact from step 1.
6. Open a sequence page. Add an Open the minigame browser action, and trigger it from an NPC dialogue, an item or a command. Or use Join a minigame with arena set to your arena to put the player straight into the lobby.
7. Publish, join the arena, click Ready in the lobby menu and wait for the countdown. When the game ends, the winner is announced and the statistics are saved.

Starting with one player

The lobby only counts down when at least minPlayers players have clicked Ready. Set minPlayers to 1 while you test alone.

How it works

1. Lobby. Players wait at lobbySpawn. The countdown starts when the number of players marked ready reaches minPlayers, after a few seconds. Late joining is only possible after the lobby when allowLateJoin is on.
2. Countdown. Lasts autoStartCountdown seconds with chat messages. If players leave and the count drops below the minimum, the game returns to the lobby.
3. Playing. Players are teleported to gameSpawn, their inventory is saved, and the kit is given. The phase ends at the latest after maxGameDuration seconds. onGameStart fires.
4. Ending. The winner and the top three are announced. This phase lasts about a sixtieth of maxGameDuration, bounded between 5 and 60 seconds.
5. Cleanup. Inventories, game mode and health are restored, results are written to the artifacts, onGameEnd fires, and players return to endTeleport.

Eliminated players become spectators and are moved to spectatorSpawn when allowSpectate is on and a spectator spawn is set.

Game modes

The gameType field of the arena accepts the 26 values below. Three modes have their own code. The 23 others are rule-based: they share one engine driven by an elimination mode and a win condition. A rule-based mode gives you the rules, the lobby, rounds and scoring. Content specific to the game name (a flag, mob waves, a rising lava floor, TNT blocks, dispensers) is not generated: you build it in the world and wire it with kits, regions and triggers.

Mode	Category	Default players	Elimination	Win condition
Sumo	PvP / Combat	2-8	Falling	Last alive
Gladiator	PvP / Combat	2-12	Killed	Last alive, power-ups every 20 s
Duels	PvP / Combat	2	Killed	Last alive
KOTH	PvP / Combat	2-16	Timeout	First to score, power-ups
Paintball	PvP / Combat	2-16	Killed	Most score
One in the Chamber	PvP / Combat	2-12	Killed	Most score
Parkour	Parkour / Movement	1	Dedicated code	Reach the end point
Block Party	Parkour / Movement	2-16	Floor gone	Last alive, up to 5 rounds
TNT Run	Parkour / Movement	2-16	Falling	Last alive
Floor is Lava	Parkour / Movement	2-16	Falling	Last alive, up to 3 rounds
Falling Blocks	PvE / Survival	1-16	Falling	Survive 120 s
Wave Survival	PvE / Survival	1-8	Killed	Survive 180 s, power-ups
Zombie Apocalypse	PvE / Survival	1-8	Killed	Survive 300 s, power-ups
Dodge the Arrows	PvE / Survival	1-16	Killed	Last alive
Defend the Core	PvE / Survival	1-8	Killed	Last team alive, 240 s
Capture the Flag	Strategy	4-16	Killed	First to score, 300 s
Infection	Strategy	2-16	Tagged	Last alive
Spleef	Strategy	2-16	Floor gone	Last alive, up to 5 rounds
Sheep Hunt	Strategy	4-16	Tagged	Most tags, 180 s
TPP (Tag)	Party / Fun	2-16	Tagged	Last alive
Freeze Tag	Party / Fun	2-16	Tagged	Last alive
Hot Potato	Party / Fun	2-16	Timeout	Last alive, 60 s
Dé à Coudre	Party / Fun	2-16	Dedicated code	Last player or team alive
Musical Chairs	Party / Fun	2-16	Timeout	Last alive, up to 10 rounds
Archery	Reflex / Arcade	1-16	Dedicated code	First to the target count, or best score in the time limit
Quake	Reflex / Arcade	2-16	Killed	Most score

The default minimum is only used when the arena minPlayers is not above zero. The maximum always comes from the arena maxPlayers.

How the rule-based modes decide

• Killed: a single hit from another player eliminates the victim, whatever the damage, and gives the attacker one point. Projectile shooters count.
• Tagged: a single hit from another player eliminates the victim and gives the tagger one point. Teammates are protected when friendly fire is off.
• Falling: a player is eliminated below ten blocks under gameSpawn.
• Floor gone: a player is eliminated when the block beneath is air.
• Timeout: no timer eliminates a player on its own. Rounds with a duration simply end when the time is up, and the scores or survivors decide the winner.
• Power-ups: when powerUpEnabled is on, a random power-up item drops every powerUpInterval seconds (at least 5). The eight types are Speed, Jump, Invisibility, Heal, Shield, Explosive Snowball, Double Jump and Super Strength.
• Rounds: with useRounds on, eliminated players are revived and everyone is replaced at gameSpawn for each round, up to maxRounds. The extension does not rebuild blocks between rounds: restore a broken floor yourself. onRoundStart fires each round.

Parkour

Parkour is a solo mode with its own configuration entry. A Parkour Arena links to a Minigame Arena of type PARKOUR and lists its start points, checkpoints and end points. A player starts the run by standing on a start point, must pass the checkpoints in increasing order, then reaches an end point.

• failAction decides what a failure does: START teleports back to the start, LAST_CHECKPOINT to the last checkpoint, QUIT abandons the run.
• timerType is NONE, GLOBAL (a fixed time in seconds) or CHECKPOINT (time plus checkpointBonus seconds at each checkpoint). Running out of time is a failure.
• A run also fails when the player changes world, drops more than 5 blocks below the start, or is more than 10 blocks from the last checkpoint.
• On completion the time is submitted for records: personal best, arena ranking, and the onPersonalBest and onWorldRecord triggers on the arena. The arena then ends because nobody is left running.

Dé à Coudre

A Dé à Coudre Arena adds a pool region, a jump location and a spawn. mode is SINGLE (players jump in turn), CONCURRENT (everyone jumps at once) or TEAM. Players start with no spare life: a missed jump eliminates the player, and a perfect jump (landing between four already-used blocks) earns one life. The lives, turn and queue placeholders show the state.

Archery

An Archery Arena lists target positions and shooting zones. mode is MAX_TARGET (first to targetsToWin hits) or TIME_ATTACK (best score within timeLimitSeconds). The extension places the targetBlock, replaces it with hitBlock when hit, and gives the bowItem and arrowItem.

Menus

The menus are 54-slot chest menus rendered by the GUI extension. They stay empty until you add an action entry that opens them.

Menu	Opened by	Content
Game browser	Open the minigame browser	A row of the six categories, then the games of the selected category. A game is only available when an arena of that type exists.
Arena selection	Open arena selection or a click in the browser	The arenas of a game type with their status (free, waiting, full, in game) and player counts. Clicking joins.
Lobby	Open the lobby menu, or automatically after joining from the menus	The arena description, player list with ready state and team, Ready, Team, Start the game and Leave buttons, plus your custom buttons.
Team selection	The Team button	Pick a team or be assigned one at random.
Statistics	Open statistics	Wins, losses, games played and a top 10, per arena or across arenas. Needs winStatArtifact on the arenas.
Results	Open the results screen	Winner, duration, player count and podium. Wire the action to the arena onGameEnd trigger.

The Start the game button is only shown to players with the minigame.start permission. A Lobby Menu entry customises the title, hides parts of the menu and adds buttons with a slot from 0 to 53 and a showCondition.

Persistence and records

Artifacts are loaded at startup and written asynchronously, so saving never blocks a game tick. Stored data is kept per arena and per player.

• Wins statistics stores wins, losses and games played, saved at cleanup for every player of the game.
• Scores statistics adds each player's score at cleanup when it is above zero.
• Minigame state is written at cleanup with the final phase, player count and winner.
• Best time and Top times store personal bests and the ranking; topTimesLimit sets how many times are kept. Today only parkour produces times.

Reset records clears the records of an arena for the triggering player (PLAYER) or for everyone (ARENA).

Quest integration

The Complete minigames objective counts completed timed runs. Leave arena empty to count every arena, or set it to count one. It stores its progress in a fact you provide and can trigger onComplete. The Minigame completions fact counts completions separately for each arena the player is in, so one fact can serve a whole network of arenas. Both currently react to parkour completions only.

Permissions

Permission	Grants
minigame.start	Shows and allows the Start the game button in the lobby menu.

There are no commands: everything is driven by entries and menus.

Placeholders

Game placeholders are available in two forms. In messages and scoreboard lines of an arena you can use %name% tokens. Elsewhere on the server, the BTC MiniPlaceholders bridge publishes the same values as <minigame_name> for a player who is in a game.

Placeholder	Returns
arena and arena_id	The arena name and entry id.
game_id	The id of the running game.
phase	The current phase name.
players and alive	Players in the game and players still alive.
max_players	The arena player limit.
winner	The winner name, or "Personne" while there is none.
score	The player's score.
alive_status	alive or eliminated.
rank	The player's rank by score, or -.
lives, turn and queue	Lives, current jumper and jump order, for Dé à Coudre only. - in other modes.
%player% (messages only)	The player name, in join, leave and elimination messages.

Entries

24 entries, generated from the extension source.

Actions9

• Minigame ForcestartForcer le démarrage d'un mini-jeu
• Minigame JoinRejoindre un mini-jeu
• Minigame LeaveQuitter un mini-jeu
• Minigame Open ArenasOuvrir la sélection d'arène
• Minigame Open BrowserOuvrir le navigateur de mini-jeux
• Minigame Open LobbyOuvrir le menu du lobby
• Minigame Open ResultsOuvrir les résultats de la partie
• Minigame Open StatsOuvrir les statistiques de mini-jeux
• Minigame Reset RecordsRéinitialiser les records d'une arène

Objectives1

• Minigame Completion ObjectiveTerminer des mini-jeux

Facts1

• Minigame Completion FactCompte les complétions d'un joueur, par arène

Artifacts5

• Minigame Best Time ArtifactStocke le meilleur temps personnel de chaque joueur par arène
• Minigame ScoresStatistiques de scores
• Minigame StateÉtat d'un mini-jeu
• Minigame Top Times ArtifactStocke le classement des meilleurs temps d'une arène
• Minigame WinsStatistiques de victoires

Manifests5

• Archery ArenaArène de tir à l'arc
• Deacoudre ArenaDé à Coudre Arena
• Minigame ArenaArène de mini-jeu
• Minigame Lobby MenuMenu du lobby
• Parkour ArenaArène de Parkour

Definitions3

• Parkour CheckpointCheckpoint du parkour
• Parkour End PointPoint d'arrivée du parkour
• Parkour Start PointPoint de départ du parkour

Troubleshooting

Menus do nothing or are empty. The menus need the GUI extension and an action entry to open them. Check that an arena of the right gameType exists: the browser marks a game type as unavailable when no arena uses it.

The game stays in the lobby forever. The countdown only starts when at least minPlayers players have clicked Ready, not simply when they are present. Lower minPlayers, or use Force start a minigame to start the countdown.

"Vous êtes déjà dans une partie". A player can only be in one game. Use Leave a minigame first. Leaving, disconnecting and finishing a game all release the player.

Nobody is ever eliminated in KILL or TAG modes. Test in survival mode with a player who can take damage: in creative mode players are invulnerable. Eliminations in these modes come from damage by another player, including arrows and snowballs.

Statistics, kills or the state artifact stay empty. An arena only writes to the artifacts it references: set winStatArtifact, scoreArtifact and stateArtifact and give each artifact an artifactId. Kills and deaths are not recorded by the current code and show 0. Best times and top times are only written by parkour.

A parkour run keeps failing. Each checkpoint must be within 10 blocks of the previous one and the run fails 5 blocks below the start point. Checkpoints must be reached in increasing order, and the end point only counts after the last checkpoint. With radius at 0 the player must stand on the exact block.

A player cannot leave the lobby area. While waiting (Lobby and Countdown phases), lobbyRadius (default 10 blocks around lobbySpawn) stops players from walking away; it does not teleport them, and a player already outside may always walk back in. Set it to 0 for no limit.

A player is eliminated for no visible reason. region is the play zone of rule-based modes: leaving it during a game eliminates the player (the region is not enforced in Archery, Parkour and Dé à Coudre, which have their own phases). In the floor-gone modes (Spleef, Block Party), floorMaterial lists the Bukkit material names that count as floor, separated by commas: a player is eliminated as soon as the block under their feet is not one of them. Empty means any non-air block is a floor, and unknown names are ignored with a warning in the console. Floors are not generated from floorMaterial; you build them.

The victory message is not the one I expected. winMessage is announced when the game ends, with %winner% replaced by the winner.

A player cannot join the arena. When every open lobby of an arena holds maxPlayers players, the arena is full and the join is refused: no second game is opened in parallel. The Join a minigame action then sends its fullMessage.

Related extensions