awesome-copilot/skills/minecraft-plugin-development/references/maps-heroes-and-feature-modules.md

Maps, Heroes, And Feature Modules

Use this reference when building map systems, rotating arenas, class systems, kits, or modular gameplay features.

Map patterns from real plugins

Per-game map-instance usage

Observed traits:

• per-game map instances
• allowed map filtering through configuration
• gameplay objects tied to the active map instance
• match mode can constrain which maps are used

This works well for isolated match instances where each game owns its world and objectives.

Persistent battlefield map rotation

Observed traits:

• one active combat world at a time
• source maps copied into temporary active worlds
• old worlds unloaded and deleted after rotation
• rotation warnings broadcast before swap
• spawn leaderboards refreshed after rotation

This works well for a persistent shared mode where the world rotates on a timer.

Sky-island arena map usage

Observed traits:

• one game owns one copied map instance
• teams are assigned to configured island spawn locations
• chests are grouped by island, middle, or center role
• countdowns control cage removal, game start, refill timing, and game end
• visibility and chat are scoped to players in the same game instance

This works well for SkyWars-style modes where every match needs isolated islands, loot, spectators, and cleanup.

Dungeon-node map usage

Observed traits:

• one game owns a lobby map plus temporary combat or event node maps
• route choices are generated from stage metadata
• players vote or confirm before advancing
• each combat node owns its wave queue and active mob set
• old node maps are unloaded only after players move to the new map or lobby

This works well for PvE roguelike, dungeon, wave, or boss progression plugins.

Guidance for map architecture

• Per-instance minigame:
  • use a GameMap owned by a game object
• Shared rotating battlefield:
  • use a MapManager with one active world plus a rotation timer
• Temporary copied worlds:
  • always teleport players out before unload
  • clean folders after unload
  • reapply gamerules after world creation
• Sky-island match:
  • group spawn and chest locations by team or island role
  • reset cages, inventories, scoreboards, and spectators per match
• Dungeon or route-node mode:
  • treat every node as a temporary stage with explicit load, enter, clear, and unload steps
  • keep mob ownership tied to the game, not just the world

Class and hero system patterns

Observed class-system traits:

• HeroRegistry
• HeroService
• definitions grouped by theme
• hero tier progression
• hero skill config and handler
• selector GUI separated from assignment logic

Observed minigame power-selection parallels:

• brands and special items function like modular player powers
• selection limits and categories are explicit
• match rules can constrain available choices

Guidance:

• keep definitions separate from runtime assignment
• use registries for discoverable content
• store unlock rules and tiers in data, not hardcoded listener branches
• separate:
  • what a class is
  • how it is selected
  • how it is applied
  • how its active skills are triggered

Feature module pattern

Good candidate modules for separate packages:

• map rotation
• hero or class system
• item powers
• boss systems
• match rules
• shops and GUIs
• scoreboards
• progression

Do not merge all these into one listener or one “game utils” class.

Practical heuristic

If a feature has all three of these, it deserves its own module:

• custom data model
• config or definitions
• one or more listeners, commands, or scheduled tasks