# Package com.codename1.gaming.level

package com.codename1.gaming.level

The saved-level / map model behind the Codename One game builder.

This package is the bridge between a visual level editor and the runtime `com.codename1.gaming` engine: a `GameLevel` is a mode-aware, JSON-serializable description of a scene that the editor writes and a game loads, decoupled from how it is drawn.

A level has a mode -- `GameLevel.Mode#TWO_D` (tile + sprite), `GameLevel.Mode#THREE_D` (meshes, `TerrainGrid` and `LevelLight`s in a perspective world) or `GameLevel.Mode#BOARD` (an `IsoProjection` grid) -- ordered `Layer`s (a tile layer paints an `assetId`-per-cell grid; entity / model layers group freely placed things), a list of `GameElement`s (pure data: an asset id, a transform and a typed property bag, not a `com.codename1.gaming.Sprite`) and an `AssetCatalog` of `AssetPack`s / `AssetDef`s resolving asset ids to artwork.

Realization -- turning the data into live objects -- depends on the mode: a `GameLevel` realizes its own 2D / board sprites, while `GameSceneView` is a turnkey `com.codename1.gaming.GameView` that plays a level end to end, including the 3D camera, lights and models (which need the GPU device).

- Related Packages
  Package
  Description
  com.codename1.gaming
  Game oriented APIs for Codename One.
  com.codename1.gaming.physics
  2D rigid body physics for Codename One games.
- Class
  Description
  AssetCatalog
  The registry that turns an `GameElement#getAssetId()` into something a `LevelRealizer` can draw.
  AssetDef
  The definition of one placeable asset in an `AssetPack`: the template a placed `GameElement` references through its `GameElement#getAssetId()`.
  AssetDef.Kind
  How an asset is placed: painted into a grid cell, or freely positioned.
  AssetDef.Type
  The art format of an asset, which decides what it is realized into.
  AssetPack
  A themed collection of `AssetDef`s -- the editor's "Platformer", "Top-Down RPG" or "Board & Card" pack.
  ChunkProvider
  Supplies and persists `TerrainChunk`s for a `StreamingTerrain`.
  GameElement
  A single placed thing in a `GameLevel` -- pure authoring data, deliberately not a `com.codename1.gaming.Sprite`.
  GameLevel
  A saved, mode-aware game level or map: the data the visual editor writes and the runtime loads, deliberately decoupled from how it is drawn.
  GameLevel.Mode
  The kind of a level, which decides how its elements are realized and rendered.
  GameSceneView
  A turnkey `GameView` that plays a `GameLevel`: it wires the whole lifecycle so a generated game scene can be a thin subclass that only adds behavior.
  GameWorld
  A large game space made of linked `Region`s, streamed in and out around the player so the world can exceed memory while transitions stay seamless.
  IsoProjection
  Maps between board cells (row, column) and screen pixels for the 2:1 isometric "diamond" layout used by board / strategy games.
  Layer
  A named drawing band in a `GameLevel`: the editor's "Background / Terrain / Items / Actors" rows, and the rendering order behind them.
  Layer.Kind
  What a layer holds, which decides how its content is realized.
  LevelLight
  A serializable directional light authored in a 3D `GameLevel`: a direction, a diffuse `#getColor()` and an `#getAmbientColor()`.
  Material
  A pluggable surface material used by terrain cells and `TerrainFeature`s.
  MaterialRegistry
  Process-wide registry of pluggable `Material`s, keyed by id.
  Region
  A loadable area of a large world: its own streaming `Terrain`, placed `GameElement`s and a world-space origin (`#getOriginX()`,`#getOriginZ()` in tile units). Regions are linked to neighbours by named edges (`#link(String,String)`, e.g. "east" -> "desert-2"), so a `GameWorld` can stream the adjacent regions in and out for seamless transitions as the player crosses a boundary.
  RegionProvider
  Loads and persists `Region`s by id for a `GameWorld`, so a world larger than memory can page whole areas in and out as the player roams.
  StreamingTerrain
  An unbounded `Terrain` that pages `TerrainChunk`s in and out through a `ChunkProvider`, keeping at most `#getCacheSize()` chunks resident (LRU).
  StreamingTerrain.MemoryChunkProvider
  A trivial in-memory provider: remembers chunks it has seen, generates empty flat-grass chunks otherwise.
  Terrain
  Abstraction over a heightfield + per-cell material + placed `TerrainFeature`s addressed by world cell coordinates.
  TerrainChunk
  A `#SIZE`x`#SIZE` square block of terrain -- the unit of streaming.
  TerrainFeature
  A placed, variable-size terrain element such as a wall, ramp or platform.
  TerrainGrid
  A height grid for a 3D `GameLevel`: a `#getCols()` x `#getRows()` array of vertex heights spaced `#getCellSize()` world units apart.
  TileLayer
  An efficient, single-tileset tile grid: a `#getCols()` x `#getRows()` array of frame indices into one `SpriteSheet` (-1 means "empty cell").