Game Assets

Every visible thing in a Game Builder level — the ground a player walks on, a coin to collect, an enemy, a 3D crate — is drawn from an asset. This chapter explains what an asset is, how assets are organized into packs and resolved by the catalog, where their artwork comes from, and how to create your own (either by authoring a pack JSON entry or by importing an image inside the editor). It closes with a note on terrain materials, a related-but-separate concept, and pointers for finding more art.

The classes live in com.codename1.gaming.level: AssetDef, AssetPack and AssetCatalog.

An asset is a reusable template — an AssetDef — not a thing in your level. It says "this is what a coin looks like and what default values a coin has," and any number of coins in any number of levels reference that one definition by id.

An AssetDef carries:

Keep this distinction clear:

When you drop a coin into a level, the editor creates a GameElement whose assetId is coin and copies the asset’s defaultProperties() into the element’s own property bag (see StarterPacks.addActor, which does exactly this with el.properties().putAll(def.defaultProperties())). You can then tweak that one coin’s value without affecting the template or any other coin. Changing the asset’s size or art, conversely, affects how every instance that references it’s drawn.

Assets are grouped into packs, and packs are indexed by a catalog:

The editor ships four starter packs in the classpath resource /gamebuilder-packs.json, loaded by StarterPacks.loadCatalog() (which calls AssetCatalog.load(InputStream)). The same catalog drives both the editor palette and a generated game’s runtime loader.

StarterPacks.defaultPackFor(mode) picks kit3d for MODE_3D, board for MODE_BOARD and platformer otherwise.

The JSON format is {"packs":[{"id":..,"name":..,"assets":[ …​ ]}]}. Here is one real asset entry from the platformer pack — the player:

Each JSON key maps onto an AssetDef field (see AssetDef.fromMap): kind is "tile" or "actor", w/h are the pixel size, color is #rrggbb, unique is a boolean, source is the optional art reference, and defaults becomes defaultProperties().

An AssetDef names an art format — TYPE_IMAGE, TYPE_SHEET or TYPE_MESH — and a getSource() art file. AssetCatalog.resolveArt() loads each asset’s art from that file into the catalog, so the same definition drives the editor palette and a shipped game.

A single .png/.jpg. resolveArt() decodes it; image(id) returns it and the level realizer wraps it in a com.codename1.gaming.Sprite. The starter packs ship one image file per asset (at the flat resource root, loaded as /<id>.png), so every starter sprite — ground, the player, the mountains — is a real file you can open in any editor and replace.

One image laid out as a grid of equal frames, plus a frame size and rate (frameW, frameH, fps). resolveArt() builds a com.codename1.gaming.SpriteSheet; the realizer creates an animated com.codename1.gaming.AnimatedSprite that the scene advances each frame. The starter coin is a six-frame sheet, so it spins at runtime with no code; image(id) returns its first frame for the editor palette.

A glTF/.glb model for a 3D level. resolveArt() keeps the file’s bytes and GameSceneView.buildModels loads them with com.codename1.gpu.GltfLoader, realizing a com.codename1.gaming.Model (and falling back to a primitive cube for an asset that has no mesh). Sprite sheets and glTF loading are existing Codename One features; the asset model just makes them first-class so the editor and runtime treat them as assets.

The Import action opens the gallery (Display#openGallery) and hands the chosen image’s bytes to GameBuilder.registerImportedAsset(…​), which builds an image AssetDef (kind from the active layer), adds it to a Custom pack and persists the PNG to <gamesDir>/assets/ plus the pack definition to <gamesDir>/custompack.json. On the next launch ProjectIO.loadCustomPack reads them back, so an imported image survives a reload. Sprite sheets and glTF meshes are added the same way at the file level — drop the file into <gamesDir>/assets/ and add a pack entry with the matching type (and frame size for a sheet); resolveArt then loads it like any other asset. (A dedicated sheet/mesh import UI is a natural follow-up.)

The bundled starter PNGs are produced once by a build-time generator (StarterArtGenerator, which draws each sprite with Graphics through AssetArt) and committed as resources — there’s no art-drawing code in the shipped runtime. Re-run the generator after changing a starter sprite or pack.

In every case the catalog falls back to the flat-colour placeholder when an asset’s art is missing, so a level is never un-renderable.

There are two practical paths.

Add an entry to a pack’s assets array using the same format as the built-ins. For example, a collectible key:

Field by field:

You can add this to a copy of gamebuilder-packs.json, or build a pack in code with new AssetPack(id, name).add(new AssetDef(…​)) and register it with catalog.addPack(pack). To give it real art, point source at a bundled art file and call catalog.resolveArt(), or supply an image directly with catalog.setImage("key", image).

The no-code path: open your level in the Game Builder, select the layer you want the asset to belong to (a tile layer for tiles, an entity/actor layer otherwise), and use the Import action ("Import your own image as a new asset"). Pick a PNG (or other supported image), and the editor creates the AssetDef and files it under the Custom pack. Once bound to a project, the editor also saves the PNG and a pack-JSON entry under the project’s games/assets/ directory as described above. The new asset appears in the palette and is immediately placeable.

3D terrain surfaces use a different, pluggable concept: materials, not sprite assets. A Material (com.codename1.gaming.level.Material) describes a surface — a base colour, whether it’s solid (blocks movement), a friction multiplier, and an optional artId for textured rendering — and is referenced everywhere by its string id.

Materials are resolved through MaterialRegistry, a process-wide registry that ships six built-ins (MaterialRegistry.GRASS, ROAD, STONE, SAND, WATER, DIRT). WATER is registered as solid. Applications add their own without changing the level format:

Unknown ids resolve to a neutral gray placeholder, so a level that references a not-yet-registered material still loads. Materials cover terrain cells and `TerrainFeature`s; the sprite/model assets covered above are a separate system.