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 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".