Maps Migration Guide

Forest to Level: What Changed

For other teams: the main game now launches LevelGameArea (a data-driven, JSON-loaded level) instead of ForestGameArea (the procedural forest demo).

This page explains what changed, why, and whether your feature is affected.

Short answer: your feature still works. LevelGameArea spawns everything ForestGameArea did.

TL;DR

• ✅ LevelGameArea has feature parity with ForestGameArea (player, weapons, consumables, loot, enemies, music, death screen).
• 🔁 The only wiring change is in MainGameScreen: it now creates LevelGameArea instead of ForestGameArea.
• 🗺️ Terrain, collision, and spawn positions now come from a map file instead of hardcoded values.
• 📦 ForestGameArea is unchanged and still in the repo, nothing was removed.

Why the change

The Maps feature replaces procedural level generation with data-driven levels: a level is a JSON file (core/assets/maps/*.json) describing typed tiles, layers, and spawn points. This lets level design happen by editing a file instead of editing Java, and gives collision real tile data to work from.

The one wiring change

MainGameScreen used to do:

ForestGameArea forestGameArea = new ForestGameArea(terrainFactory);
forestGameArea.create();

It now does:

LevelGameArea levelGameArea = new LevelGameArea(terrainFactory, "maps/demo.json");
levelGameArea.create();
fitCameraToMap(levelGameArea);

The death-screen check in render() now calls levelGameArea.isPlayerDead() (same method ForestGameArea had).

What LevelGameArea.create() does

flowchart TB
  A["mapLoader.load('maps/demo.json')"] --> B[loadAssets]
  B --> C[spawnTerrain — render tiles]
  C --> D[spawnCollisions — colliders from tile data]
  D --> E[spawnPlayer — at map player spawn]
  E --> F[spawnEnemies — at map enemy spawns]
  F --> G[spawnLoot — weapons, consumables, gold]
  G --> H[playMusic]

Loading

Feature parity checklist

Feature (from ForestGameArea)	In LevelGameArea?
Player (all components, combat, inventory)	✅ same PlayerFactory.createPlayer()
Weapons (bow, sword)	✅ WeaponGenerator + LootFactory
Consumables (one of each)	✅ ConsumableGenerator + LootFactory
Gold coin loot	✅
Ghosts + ghost king	✅ (positions from the map)
Background music	✅
Death screen (isPlayerDead)	✅
Trees / single hardcoded platform	➖ replaced by map tiles

The 3 differences that affect you

1. Terrain + collision come from the map file. Instead of four hardcoded boundary walls and one platform, colliders are generated per tile from the map's collision layer (SOLID/PLATFORM tiles become colliders; HAZARD tiles damage the player).
2. Spawn positions come from the map. Player, enemy, and loot positions are read from the map's spawns section, not from constants in the game area.
3. The camera is fit to the map so the loaded level fills the window.

"Where do I add my entity?"

Spawn it in LevelGameArea, mirroring how ForestGameArea did it, ideally driven by the map's spawn data. The existing spawnLoot() and spawnEnemies() methods are the pattern to copy:

// Fixed position:
spawnEntityAt(myEntity, new GridPoint2(x, y), true, true);

// Or from the map's spawn data:
for (SpawnPoint sp : getMapData().getSpawns().getEnemies()) {
  spawnEntityAt(makeEnemy(sp.getType()), sp.getPosition(), true, true);
}

If your feature spawns entities in the game area, add a spawnX() method and call it from create().

Gotchas

• Tile PNGs must all be the same pixel size (e.g. 256×256), or tiles render with gaps/overlap.
• Loot falls gravity is on, so dropped items settle onto the nearest floor/platform.
• Hazard tiles damage the player on contact (handled by the collision layer, #16).

See also

• Tile-Based Level Map — overview.
• Tile-Based Level Map: Technical Reference — classes, API, format.