# Class GameElement

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

public class GameElement extends Object

A single placed thing in a `GameLevel` -- pure authoring data, deliberately not a `com.codename1.gaming.Sprite`.

An element only describes what (an `#getAssetId()` resolved through an `AssetCatalog`), where (a position / rotation / scale transform), which `Layer` it belongs to, and a bag of typed authoring `#properties()` (a coin's `value`, a patrolling enemy's `speed`, a player's `lives`). What it becomes at runtime depends on the level's `GameLevel#getMode()`: a `LevelRealizer` turns a 2D / board element into a `com.codename1.gaming.Sprite` and a 3D element into a `com.codename1.gaming.Model`. The realized object keeps a reference back to its element through `setUserData`, so an editor can map a picked sprite/model to the data it came from.

The property bag stores values as they survive JSON: `Double` for numbers, `String` for text, `Boolean` for flags. The typed getters coerce defensively so callers do not care whether a number arrived as a `Double`, a `Long` or a numeric `String`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GameElement()`
  `GameElement(String id, String assetId)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `getAssetId()`
  The catalog id of the asset this element draws (e.g. `"player"`, `"coin"`).
  `boolean`
  `getBoolean(String key, boolean defaultValue)`
  Reads a property as a boolean.
  `double`
  `getDouble(String key, double defaultValue)`
  Reads a property as a double, coercing `Number` and numeric `String` values.
  `String`
  `getId()`
  `int`
  `getInt(String key, int defaultValue)`
  Reads a property as an int, coercing `Number` and numeric `String` values and falling back to `defaultValue` when the key is missing or not numeric.
  `String`
  `getLayer()`
  The name of the `Layer` this element belongs to.
  `String`
  `getName()`
  The optional display name typed in the editor's Inspector.
  `Object`
  `getProperty(String key)`
  The raw value of an authoring property, or `null` if unset.
  `float`
  `getRotation()`
  The rotation in degrees (clockwise in 2D, applied about the model's axes in 3D).
  `float`
  `getScaleX()`
  The per-instance x scale (`1` = the asset's natural size).
  `float`
  `getScaleY()`
  The per-instance y scale (`1` = the asset's natural size).
  `float`
  `getScaleZ()`
  The per-instance z scale, used in 3D (`1` = the asset's natural size).
  `String`
  `getString(String key, String defaultValue)`
  Reads a property as a String (any value's `toString()`), or `defaultValue` if absent.
  `double`
  `getX()`
  The x position -- pixels in a 2D / board level, a world-space coordinate in 3D.
  `double`
  `getY()`
  The y position -- pixels in a 2D / board level, a world-space coordinate in 3D.
  `double`
  `getZ()`
  The world-space depth, meaningful only in `GameLevel.Mode#THREE_D`.
  `boolean`
  `hasProperty(String key)`
  Whether an authoring property with the given key is set.
  `Map<String,Object>`
  `properties()`
  The mutable authoring property bag.
  `AssetDef`
  `resolveDef(AssetCatalog catalog)`
  The `AssetDef` this element's `#getAssetId()` resolves to in the given catalog, cached after the first lookup.
  `GameElement`
  `setAssetId(String assetId)`
  Points this element at a different catalog asset (and clears the cached `#resolveDef`).
  `GameElement`
  `setId(String id)`
  Sets this element's stable id (unique within a level; the editor assigns one).
  `GameElement`
  `setLayer(String layer)`
  Moves this element to the named `Layer`.
  `GameElement`
  `setName(String name)`
  Sets the display name (see `#getName()`).
  `GameElement`
  `setPosition(double x, double y)`
  Sets the x and y position (see `#getX()`).
  `GameElement`
  `setPosition(double x, double y, double z)`
  Sets the x, y and z position (z is the 3D depth).
  `GameElement`
  `setProperty(String key, Object value)`
  Sets an authoring property (a coin's `value`, an enemy's `speed`, ...).
  `GameElement`
  `setRotation(float rotation)`
  Sets the rotation in degrees (see `#getRotation()`).
  `GameElement`
  `setScale(float scale)`
  Sets a uniform scale on all three axes.
  `GameElement`
  `setScale(float scaleX, float scaleY, float scaleZ)`
  Sets the per-axis scale (z applies in 3D).
  `GameElement`
  `setX(double x)`
  Sets the x position.
  `GameElement`
  `setY(double y)`
  Sets the y position.
  `GameElement`
  `setZ(double z)`
  Sets the z (3D) depth.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### GameElement

    public GameElement()

  - ### GameElement

    public GameElement(String id, String assetId)

- ## Method Details

  - ### getId

    public String getId()

  - ### setId

    public GameElement setId(String id)
    Sets this element's stable id (unique within a level; the editor assigns one).

  - ### getName

    public String getName()
    The optional display name typed in the editor's Inspector. A named element becomes a generated field in the companion class; may be `null`.

  - ### setName

    public GameElement setName(String name)
    Sets the display name (see `#getName()`).

  - ### getAssetId

    public String getAssetId()
    The catalog id of the asset this element draws (e.g. `"player"`, `"coin"`).

  - ### setAssetId

    public GameElement setAssetId(String assetId)
    Points this element at a different catalog asset (and clears the cached `#resolveDef`).

  - ### resolveDef

    public AssetDef resolveDef(AssetCatalog catalog)
    The `AssetDef` this element's `#getAssetId()` resolves to in the given catalog, cached after the first lookup. The element stays pure, catalog-independent data (only the id is stored and serialized); this just spares per-frame callers a repeated catalog-map lookup. Returns `null` for a null catalog or an unknown id. The cache is cleared by `#setAssetId`; if you re-register an asset under the same id, build a fresh element or set the id again.

  - ### getLayer

    public String getLayer()
    The name of the `Layer` this element belongs to.

  - ### setLayer

    public GameElement setLayer(String layer)
    Moves this element to the named `Layer`.

  - ### getX

    public double getX()
    The x position -- pixels in a 2D / board level, a world-space coordinate in 3D.

  - ### getY

    public double getY()
    The y position -- pixels in a 2D / board level, a world-space coordinate in 3D.

  - ### getZ

    public double getZ()
    The world-space depth, meaningful only in `GameLevel.Mode#THREE_D`.

  - ### setPosition

    public GameElement setPosition(double x, double y)
    Sets the x and y position (see `#getX()`).

  - ### setPosition

    public GameElement setPosition(double x, double y, double z)
    Sets the x, y and z position (z is the 3D depth).

  - ### setX

    public GameElement setX(double x)
    Sets the x position.

  - ### setY

    public GameElement setY(double y)
    Sets the y position.

  - ### setZ

    public GameElement setZ(double z)
    Sets the z (3D) depth.

  - ### getRotation

    public float getRotation()
    The rotation in degrees (clockwise in 2D, applied about the model's axes in 3D).

  - ### setRotation

    public GameElement setRotation(float rotation)
    Sets the rotation in degrees (see `#getRotation()`).

  - ### getScaleX

    public float getScaleX()
    The per-instance x scale (`1` = the asset's natural size).

  - ### getScaleY

    public float getScaleY()
    The per-instance y scale (`1` = the asset's natural size).

  - ### getScaleZ

    public float getScaleZ()
    The per-instance z scale, used in 3D (`1` = the asset's natural size).

  - ### setScale

    public GameElement setScale(float scale)
    Sets a uniform scale on all three axes.

  - ### setScale

    public GameElement setScale(float scaleX, float scaleY, float scaleZ)
    Sets the per-axis scale (z applies in 3D).

  - ### properties

    public Map<String,Object> properties()
    The mutable authoring property bag. Values are `Double` / `String` / `Boolean` (or nested `Map` / `List` if you store structured data). Prefer the typed getters for reading.

  - ### hasProperty

    public boolean hasProperty(String key)
    Whether an authoring property with the given key is set.

  - ### setProperty

    public GameElement setProperty(String key, Object value)
    Sets an authoring property (a coin's `value`, an enemy's `speed`, ...). Store `Double` / `String` / `Boolean` so the value survives a JSON round-trip.

  - ### getProperty

    public Object getProperty(String key)
    The raw value of an authoring property, or `null` if unset. Prefer the typed getters.

  - ### getInt

    public int getInt(String key, int defaultValue)
    Reads a property as an int, coercing `Number` and numeric `String` values and falling back to `defaultValue` when the key is missing or not numeric.

  - ### getDouble

    public double getDouble(String key, double defaultValue)
    Reads a property as a double, coercing `Number` and numeric `String` values.

  - ### getString

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

  - ### getBoolean

    public boolean getBoolean(String key, boolean defaultValue)
    Reads a property as a boolean. Accepts a `Boolean` or the strings `"true"`/`"1"`.