# Class GameLevel

java.lang.Object
com.codename1.gaming.level.GameLevel

public class GameLevel extends Object

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.

A level has a `#getMode()` -- `Mode#TWO_D` (tiles + sprites), `Mode#THREE_D` (meshes in a perspective world with terrain and lights) or `Mode#BOARD` (an isometric grid) -- an `#getAssetPack()` it draws from, a grid size, ordered `Layer`s, freely placed `GameElement`s, and mode-specific extras (a camera rig, `#lights()`, `#getTerrain()`). It is pure data: load it with `#load(String)`, edit it, `#toJson()` it back. Turning it into live objects is the realizer's job -- `#realizeSprites(Scene, AssetCatalog)` builds the 2D / board sprites here, while `GameSceneView` wires the full lifecycle (including the 3D camera and lights, which need the GPU device).

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `GameLevel.Mode`
  The kind of a level, which decides how its elements are realized and rendered.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GameLevel()`
  `GameLevel(GameLevel.Mode mode)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `GameLevel`
  `addElement(GameElement element)`
  Adds a placed element to the level.
  `GameLevel`
  `addLayer(Layer layer)`
  Appends a layer to the stack.
  `List<GameElement>`
  `elements()`
  The placed `GameElement`s, across all layers; mutable.
  `String`
  `getAssetPack()`
  The id of the `AssetPack` this level's elements draw from.
  `int`
  `getCols()`
  The grid width in cells.
  `double`
  `getDouble(String key, double def)`
  A level property as a double, coerced from a `Number`/numeric `String`, else `def`.
  `float`
  `getEyeX()`
  `float`
  `getEyeY()`
  `float`
  `getEyeZ()`
  `float`
  `getFar()`
  `float`
  `getFov()`
  `int`
  `getInt(String key, int def)`
  A level property as an int, coerced from a `Number`/numeric `String`, else `def`.
  `Layer`
  `getLayer(String name)`
  The layer with the given name, or `null` if there is none.
  `GameLevel.Mode`
  `getMode()`
  This level's `Mode`.
  `float`
  `getNear()`
  `int`
  `getRows()`
  The grid height in cells.
  `String`
  `getString(String key, String def)`
  A level property as a String (any value's `toString()`), or `def` if absent.
  `float`
  `getTargetX()`
  `float`
  `getTargetY()`
  `float`
  `getTargetZ()`
  `TerrainGrid`
  `getTerrain()`
  `int`
  `getTileSize()`
  The size of one grid cell -- pixels per tile in 2D / board, world units per cell in 3D.
  `GameWorld`
  `getWorld()`
  The streaming/region world backing a "large world" level, or null for a bounded level.
  `boolean`
  `is2D()`
  True for an orthographic 2D level (`Mode#TWO_D`).
  `boolean`
  `is3D()`
  True for a perspective 3D level (`Mode#THREE_D`).
  `boolean`
  `isBoard()`
  True for an isometric board level (`Mode#BOARD`).
  `boolean`
  `isLargeWorld()`
  True when this level is backed by a streaming `GameWorld` of regions rather than a single bounded grid.
  `List<Layer>`
  `layers()`
  The ordered `Layer` stack (low band first); mutable.
  `List<LevelLight>`
  `lights()`
  `static GameLevel`
  `load(InputStream in)`
  Parses a level from a UTF-8 JSON stream and closes it.
  `static GameLevel`
  `load(String json)`
  Parses a level from a JSON string.
  `Map<String,Object>`
  `props()`
  The level-wide authoring property bag (gravity, background, ...).
  `void`
  `realizeSprites(Scene scene, AssetCatalog catalog)`
  Builds `Sprite`s for the 2D / board content of this level and adds them to the scene: every painted tile of each visible `Layer.Kind#TILE` layer plus every `GameElement` whose layer is an entity layer.
  `void`
  `realizeSprites(Scene scene, AssetCatalog catalog, IsoProjection projection)`
  `void`
  `save(OutputStream out)`
  Writes this level as UTF-8 JSON to the stream (does not close it).
  `GameLevel`
  `setAssetPack(String assetPack)`
  Sets the asset-pack id (see `#getAssetPack()`).
  `GameLevel`
  `setCamera(float eyeX, float eyeY, float eyeZ, float targetX, float targetY, float targetZ)`
  `GameLevel`
  `setGrid(int cols, int rows, int tileSize)`
  Sets the grid dimensions and cell size in one call.
  `GameLevel`
  `setLens(float fov, float near, float far)`
  `GameLevel`
  `setMode(GameLevel.Mode mode)`
  `GameLevel`
  `setTerrain(TerrainGrid terrain)`
  `GameLevel`
  `setWorld(GameWorld world)`
  `String`
  `toJson()`
  Serializes this level to a compact JSON string (round-trips through `#load(String)`).

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### GameLevel

    public GameLevel()

  - ### GameLevel

    public GameLevel(GameLevel.Mode mode)

- ## Method Details

  - ### getMode

    public GameLevel.Mode getMode()
    This level's `Mode`.

  - ### setMode

    public GameLevel setMode(GameLevel.Mode mode)

  - ### is2D

    public boolean is2D()
    True for an orthographic 2D level (`Mode#TWO_D`).

  - ### is3D

    public boolean is3D()
    True for a perspective 3D level (`Mode#THREE_D`).

  - ### isBoard

    public boolean isBoard()
    True for an isometric board level (`Mode#BOARD`).

  - ### getAssetPack

    public String getAssetPack()
    The id of the `AssetPack` this level's elements draw from.

  - ### setAssetPack

    public GameLevel setAssetPack(String assetPack)
    Sets the asset-pack id (see `#getAssetPack()`).

  - ### getCols

    public int getCols()
    The grid width in cells.

  - ### getRows

    public int getRows()
    The grid height in cells.

  - ### getTileSize

    public int getTileSize()
    The size of one grid cell -- pixels per tile in 2D / board, world units per cell in 3D.

  - ### setGrid

    public GameLevel setGrid(int cols, int rows, int tileSize)
    Sets the grid dimensions and cell size in one call.

  - ### props

    public Map<String,Object> props()
    The level-wide authoring property bag (gravity, background, ...).

  - ### getDouble

    public double getDouble(String key, double def)
    A level property as a double, coerced from a `Number`/numeric `String`, else `def`.

  - ### getInt

    public int getInt(String key, int def)
    A level property as an int, coerced from a `Number`/numeric `String`, else `def`.

  - ### getString

    public String getString(String key, String def)
    A level property as a String (any value's `toString()`), or `def` if absent.

  - ### layers

    public List<Layer> layers()
    The ordered `Layer` stack (low band first); mutable.

  - ### addLayer

    public GameLevel addLayer(Layer layer)
    Appends a layer to the stack.

  - ### getLayer

    public Layer getLayer(String name)
    The layer with the given name, or `null` if there is none.

  - ### elements

    public List<GameElement> elements()
    The placed `GameElement`s, across all layers; mutable.

  - ### addElement

    public GameLevel addElement(GameElement element)
    Adds a placed element to the level.

  - ### lights

    public List<LevelLight> lights()

  - ### getTerrain

    public TerrainGrid getTerrain()

  - ### setTerrain

    public GameLevel setTerrain(TerrainGrid terrain)

  - ### getWorld

    public GameWorld getWorld()
    The streaming/region world backing a "large world" level, or null for a bounded level. When set, the active region's `StreamingTerrain` is the authoritative terrain and the bounded `#getTerrain()` grid is unused. Serialized inline under the "world" key.

  - ### setWorld

    public GameLevel setWorld(GameWorld world)

  - ### isLargeWorld

    public boolean isLargeWorld()
    True when this level is backed by a streaming `GameWorld` of regions rather than a single bounded grid.

  - ### setCamera

    public GameLevel setCamera(float eyeX, float eyeY, float eyeZ, float targetX, float targetY, float targetZ)

  - ### setLens

    public GameLevel setLens(float fov, float near, float far)

  - ### getEyeX

    public float getEyeX()

  - ### getEyeY

    public float getEyeY()

  - ### getEyeZ

    public float getEyeZ()

  - ### getTargetX

    public float getTargetX()

  - ### getTargetY

    public float getTargetY()

  - ### getTargetZ

    public float getTargetZ()

  - ### getFov

    public float getFov()

  - ### getNear

    public float getNear()

  - ### getFar

    public float getFar()

  - ### realizeSprites

    public void realizeSprites(Scene scene, AssetCatalog catalog)

    Builds `Sprite`s for the 2D / board content of this level and adds them to the scene: every painted tile of each visible `Layer.Kind#TILE` layer plus every `GameElement` whose layer is an entity layer. Each sprite's z-order is its layer band times 1000 (so a higher layer always draws on top), and its `Sprite#getUserData()` is the source `GameElement` (for tiles, the source `Layer`), so an editor can map a picked sprite back to its data.

    In `Mode#THREE_D` this is a no-op (3D content is realized by `GameSceneView` once the GPU device exists). In `Mode#BOARD` positions go through `projection` (board elements store their column/row in x/y), so pass a fitted `IsoProjection`.

  - ### realizeSprites

    public void realizeSprites(Scene scene, AssetCatalog catalog, IsoProjection projection)

  - ### load

    public static GameLevel load(String json) throws IOException
    Parses a level from a JSON string.
    Throws:
      `IOException`

  - ### load

    public static GameLevel load(InputStream in) throws IOException
    Parses a level from a UTF-8 JSON stream and closes it.
    Throws:
      `IOException`

  - ### toJson

    public String toJson()
    Serializes this level to a compact JSON string (round-trips through `#load(String)`).

  - ### save

    public void save(OutputStream out) throws IOException
    Writes this level as UTF-8 JSON to the stream (does not close it).
    Throws:
      `IOException`