hyperlap2d-mcp
Drive the HyperLap2D 2D scene editor from an MCP client (create/modify entities & components, list assets, screenshot, scene settings, shaders, z-ordering, layers). Use whenever the running editor's MCP server is connected and the task is to build or inspect a HyperLap2D scene.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/rednblackgames--hyperlap2d)HTML
<a href="/listings/rednblackgames--hyperlap2d"><img src="/api/listings/rednblackgames--hyperlap2d/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 268 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: hyperlap2d-mcp
- description: Drive the HyperLap2D 2D scene editor from an MCP client (create/modify entities & components, list assets, screenshot, scene settings, shaders, z-ordering, layers). Use whenever the running editor's MCP server is connected and the task is to build or inspect a HyperLap2D scene.
- ---
- # HyperLap2D MCP Server — Tool Guide
- The HyperLap2D editor exposes an MCP server (Streamable HTTP) that lets an external client drive it: create and modify entities and components, list assets, capture screenshots, change scenes and scene settings, create shaders, control z-ordering, and manage layers. This skill documents every tool, the editor's coordinate/layer model, and the edge cases that bite when authoring a scene blind.
- ## Prerequisites & connection
- 1. The editor is running (`./gradlew runHyperLap2D`) with a project open and a scene loaded.
- 2. **Settings → Plugins → "MCP Server"** is enabled (and the port set). The server starts/stops live on toggle.
- 3. The MCP client connects to `http://127.0.0.1:<port>/mcp` (Streamable HTTP). Configure it like:
- ```json
- { "mcpServers": { "hyperlap2d": { "url": "http://127.0.0.1:8765/mcp" } } }
- ```
- 4. If a tool returns "no scene loaded" / "no current scene", open a project and scene in the editor first. If `list_*` tools return empty, no project/scene is loaded.
- All tool calls run on the editor's render thread via an internal bridge; they are synchronous with a timeout (≈5s, 15s for screenshots). Keep the editor open while calling.
- ## Core model (read this before placing anything)
- - **World units, not pixels.** Entity `x`, `y`, `width`, `height` are in **world units**. One world unit = `pixelsPerWU` pixels. A value like `300` can be enormous or tiny depending on `pixelsPerWU` — **always read `pixelsPerWU` first** (`get_scene_settings` or `get_asset_dimensions`) before choosing coordinates.
- - **Asset world size = pixel size / pixelsPerWU.** Use `get_asset_dimensions` to get each region's pixel + world width/height so you can place tiles the right distance apart.
- - **Never guess an asset's appearance from its name.** Use `get_asset_preview` to actually see the source PNG before placing it. Names like `walls3` or `plant1` tell you nothing reliable about content or scale.
- - **Coordinate origin.** The editor scene camera is y-down (origin top-left, +y downward). Entity `(x, y)` is the entity's position **in its parent composite's local space**, never in absolute scene space.
- - **Layers + z-index.** Every entity belongs to a **layer** (named, e.g. `Default`) and has a **z-index** that is *local to that layer*. Lower z-index draws behind, higher draws in front. The runtime auto-adjusts z-indices into a linear progression, so setting an absolute integer is the intended usage (`set_z_index`). Read current order from `list_entities` (`zIndex` + `layer` fields). **Layers are per-composite** (each composite — including the scene root — has its own layer list) and layer names are **case-sensitive** in the editor (stored by hash; the default layer is `Default`). The layer tools resolve names case-insensitively, so `"default"` matches `Default` — but when creating/renaming you pass the exact name you want.
- - **Composites — everything lives in one.** A composite is a container entity that holds children. **The scene root is itself a composite**, so *every* entity has a parent composite and *every* `(x, y)` is local to that parent. A child's coordinates are an offset from its composite's origin — **not** a scene-absolute position. Creating a child at `(5.5, 0)` inside a composite places it 5.5 units from *that composite's* origin, wherever the composite sits.
- - **The first child of a new composite lands at the composite's origin — this is correct, not a bug.** With `automaticResize` (the default), the composite has no size until it has children; the first child you add *defines* the origin of the local space, so it sits at local `(0, 0)` regardless of the coordinates you pass. This is the whole point of a composite. Build the group so its first/anchor child is the one meant to be at the origin, then add the rest relative to it, then position the composite (see **Building a composite correctly**). Never treat the first-child-at-origin as something to "fix" by deleting/recreating — you'll only scramble the group.
- - **Lights belong to the object they light, not to a "lights" group.** A point/cone light is placed *next to the object it illuminates, inside that object's composite/hierarchy* — a lamp light goes in the lamp's composite at the lamp's position, a glow light goes on the glowing prop. Do **not** collect all lights into a separate `lights` composite or treat lighting as a render layer; that is not how HyperLap2D lighting works. Light position is meaningful and must track its object, so keep them together (moving the object then moves its light).
- - **Validation is sacred.** Component add/edit goes through the *same properties panels* the UI uses. Invalid values or disallowed components are rejected with the same messages the panels produce. Do not try to "work around" a rejected value — it's rejected because the editor considers it invalid.
- ## Golden rules for scene authoring
- 1. `get_scene_settings` → note `pixelsPerWU`.
- 2. `list_assets` → know what's available.
- 3. `get_asset_dimensions` → learn each region's world size.
- 4. `get_asset_preview` → *see* the assets you plan to use.
- 5. `create_entity` / `create_entities` at correct world coordinates (computed from pixelsPerWU and asset world sizes).
- 6. `set_z_index` to order layers/depth.
- 7. `screenshot` (mode `whole` or `region`) to let the user verify.
- Do not place entities blindly; do not invent asset semantics. The user judges all visual results — your job is correct, validated structure.
- ---
- ## Tool reference
- 28 tools. Grouped by purpose.
- ### Discovery (read-only)
- #### `list_scenes`
- No args. Returns `[{ "name": ... }]` — all scenes in the open project.
- #### `list_entities`
- No args. Returns a flat array of every entity in the current scene:
- `{ uniqueId, parentId, name, typeId, type, depth, zIndex, layer }`
- - `uniqueId` — the stable id you pass to all mutation tools.
- - `parentId` — null for direct children of the scene root; otherwise the parent composite's uniqueId. Use with `depth` to rebuild the tree.
- - `type` — display name (covers core + Spine/Talos/TinyVG).
- - `zIndex`, `layer` — the per-layer z-index and layer name (mirror of `set_z_index`).
- #### `list_assets`
- No args. Returns loaded project assets grouped by category:
- `imageRegion`, `ninePatchRegion`, `spineAnimation`, `spriteAnimation`, `particleEffect`, `talosEffect`, `font`, `tinyvg`, `shader`.
- Use region names for `create_entity` (image/9patch) and shader names for `update_component`/`update_scene_settings`.
- #### `get_asset_dimensions`
- No args. Returns `{ pixelsPerWU, regions: [{ name, pixelWidth, pixelHeight, worldWidth, worldHeight, ninePatch }] }` for all image/nine-patch regions. `worldWidth = pixelWidth / pixelsPerWU`. Use to plan placement spacing.
- #### `get_asset_preview`
- Args: `name` (required), `folder` (optional, default `<projectPath>/assets/orig/images`). Returns the source `<name>.png` as MCP **image content** plus text with `pixelWidth`/`pixelHeight`/`path`. Use to see an asset before placing it. If the PNG isn't in the default folder, pass `folder` to point elsewhere.
- #### `get_scene_settings`
- No args. Returns `{ sceneName, pixelsPerWU, shader, physicsEnabled, gravityX, gravityY, sleepVelocity, lightsEnabled, pseudo3d, blurNum, lightMapScale, lightType, directionalRays, directionalDegree, directionalHeight, ambientColor, directionalColor }`. Colors are `[r,g,b,a]` lists.
- #### `get_editable_components`
- Args: `entityId`. Returns `{ editable: [...], addable: [...] }` — the componentKeys whose panel currently applies to that entity (for `update_component`) and the components it can still have added (for `add_component`). **Use this when unsure** what an entity accepts; it's the single source of truth shared with the validation path.
- #### `list_actions`
- No args. Returns the library action-graph names in the project (the node-graph actions attachable to entities). (Actions are out of scope for creation via MCP — listed only.)
- ### Mutation (validated, undoable unless noted)
- #### `create_entity`
- Args: `type` (required), `name`, `x`, `y`, `width`, `height`, `fontFamily`, `fontSize`, `lightType`, `parentUniqueId`, `layer`.
- - `type`: `image | spriteAnimation | spineAnimation | libraryItem | 9patch | tinyvg | particle | talos | primitive | composite | label | light`.
- - Name-based types (`image`, `spriteAnimation`, `spineAnimation`, `libraryItem`, `9patch`, `tinyvg`, `particle`, `talos`) require `name` from `list_assets`.
- - `primitive`: `width`/`height` (default 100) define the rect at creation.
- - `label`: optional `fontFamily` (must be a loaded font) / `fontSize` (default 20).
- - `light`: `lightType` `POINT` (default) or `CONE`.
- - `parentUniqueId`: create **inside** that composite; `x`/`y` then become **local to the composite** (offsets from its origin, not scene-absolute — see Edge cases → *Building a composite correctly*, and lay children out around `(0,0)`, not at their intended world positions). The composite must be a **direct child of the current viewing entity**. To target a nested composite, enter its container in the editor first.
- - `layer`: create on a named layer (resolved case-insensitively; must exist on the effective parent — see `list_layers`). When omitted, the entity uses the currently selected layer.
- - Returns the new entity's `uniqueId`. Creation is undoable (Ctrl+Z).
- #### `create_entities` (bulk)
- Args: `entities` (array of specs with the same fields as `create_entity`, including `parentUniqueId` and `layer`). Creates each sequentially via the same validated/undoable path. Returns a JSON array of `{ ok, uniqueId, error }` in input order. Use for placing many tiles/objects at once instead of many `create_entity` round-trips. Some entries can fail without aborting the rest.
- #### `update_transform`
- Args: `entityId`, `fields` (object). Fields: `x`, `y`, `width`, `height`, `scaleX`, `scaleY`, `rotation`, `flipX`, `flipY`, `id`, `tint`. Pass only what you want to change. Drives the basic properties panel (validated, undoable).
- - **`width`/`height` are editable only for label, composite, and 9-patch entities.** For images/sprites/spine/etc. size comes from the asset — use `scaleX`/`scaleY`. For **primitives**, see Edge cases (width/height are *not* the size; the polygon vertices are).
- #### `update_component`
- Args: `entityId`, `componentKey`, `fields` (object). Drives that component's properties panel (validated, undoable). Pass only the fields to change. `componentKey` selects the panel and the accepted fields:
- | componentKey | applies to | fields |
- |---|---|---|
- | `basic` | all entities | x, y, width, height, scaleX, scaleY, rotation, flipX, flipY, id, tint |
- | `label` | label entities | text, fontFamily, bitmapFont, fontSize, align, wrap, mono |
- | `particle` | particle effects | matrixTransform, autoStart |
- | `image` | images | renderMode, spriteType |
- | `composite` | composites | scissorsEnabled, renderToFBO, automaticResize |
- | `sprite` | sprite animations | fps, animation, playMode |
- | `spine` | spine animations | animation, skin |
- | `talos` | talos effects | matrixTransform, autoStart |
- | `lightItem` | light entities | type, rayCount, radius, angle, distance, direction, intensity, height, softnessLength, falloff, isStatic, isXRay, isSoft, isActive |
- | `shader` | entities with a Shader component | shaderName, renderingLayer |
- | `physics` | entities with Physics | mass, density, friction, restitution, damping, angularDamping, gravityScale, height, centerOfMassX, centerOfMassY, rotationalInertia, bodyType, shapeType, allowSleep, awake, bullet, sensor, fineBoundBox, fixedRotation |
- | `light` | entities with a Light component | rays, distance, intensity, constantFalloff, linearFalloff, quadraticFalloff, softnessLength, height, direction, isStatic, isXRay, isSoft, isActive, color |
- | `circle` | entities with Circle Shape | radius |
- | `polygon` | entities with Polygon Shape | verticesCount, openPath |
- | `sensor` | entities with Sensor | sensorTop/Bottom/Left/Right, spanPercentTop/Bottom/Left/Right, heightPercentTop/Bottom, widthPercentLeft/Right |
- | `layout` | entities with Layout | leftMargin/rightMargin/bottomMargin/topMargin, horizontalBias/verticalBias, leftEnabled/rightEnabled/bottomEnabled/topEnabled, leftTarget/rightTarget/bottomTarget/topTarget, leftSide/rightSide/bottomSide/topSide, matchWidth/matchHeight |
- For shape/physics/light/etc. components, the entity must already have that component — `add_component` it first (or check `get_editable_components`).
- #### `add_component`
- Args: `entityId`, `componentKey`. `componentKey` ∈ `Polygon Shape | Circle Shape | Physics | Physics Sensors | Shader | Light | Typing Label | Layout`. Allowed set is enforced editor-side (Light/Shader can't be added to light entities; Typing Label only to labels; already-present rejected). Undoable.
- #### `remove_component`
- Args: `entityId`, `componentKey` (same keys). Only the removable components above. Undoable.
- #### `set_z_index`
- Args: `entityId`, `zIndex` (integer). Sets the entity's z-index to an absolute value **local to its layer**. Lower draws behind, higher in front; the runtime auto-adjusts z-indices into a linear progression. Undoable (Ctrl+Z). Read the result back via `list_entities` (`zIndex`, `layer`).
- #### `delete_entity`
- Args: `entityId`. Selects then runs the standard delete command. Undoable.
- #### `delete_entities` (bulk)
- Args: `entityIds` (array of strings). Deletes each via the standard path. Returns `[{ entityId, ok, error }]` in input order. Some can fail (e.g. not found) without aborting the rest.
- #### `open_scene`
- Args: `sceneName` (from `list_scenes`). Routes through the editor's unsaved-changes check (may prompt/save in the UI), then loads the scene. Timeout 30s; if the user cancels a save dialog the request times out.
- #### `update_scene_settings`
- Args: `fields` (object). Drives the scene properties panel (validated, undoable). Fields: `physicsEnabled`, `gravityX`, `gravityY`, `sleepVelocity`, `lightsEnabled`, `pseudo3d`, `blurNum`, `lightMapScale`, `lightType` (`DIFFUSE`/`DIRECTIONAL`/`BRIGHT`), `directionalRays`, `directionalDegree`, `directionalHeight` (only when `lightType=DIRECTIONAL`), `ambientColor`, `directionalColor`, `shader`. Pass only what you want to change.
- #### `create_shader`
- Args: `name` (required, unique), `templateType` (0=Default Array, 1=Distance Field, 2=Screen Reading), optional `vertex` + `fragment` (custom GLSL, overrides template). Writes `.vert`/`.frag`, compile-checks first (a failed compile leaves no files), registers the shader. Then apply it with `update_component` (`shaderName`) on an entity, or `update_scene_settings` (`shader`) for the scene shader.
- #### `save_project`
- No args. Saves the current project (all scenes and assets) to disk.
- ### Layers
- Layers belong to the **current viewing entity** (the scene root, or the composite currently being edited) — they are per-composite. Layer tools resolve layer names **case-insensitively** (so `"default"` matches `Default`), but the editor stores names case-sensitively; `create_layer`/`rename_layer` apply the name you pass exactly. `create`/`delete`/`rename`/`set_layer_order`/`set_entity_layer` all run through the editor's undoable layer commands.
- #### `list_layers`
- No args. Returns `[{ name, index, isVisible, isLocked }]` for the current viewing entity's layers, in editor order (index 0 = back-most layer). Use to learn exact layer names before referencing them.
- #### `create_layer`
- Args: `layerName`. Creates a new layer on the current viewing entity; `layerName` is used as-is (case-sensitive). Rejected if a same-cased or case-insensitive match already exists. Undoable.
- #### `delete_layer`
- Args: `layerName` (matched case-insensitively). Deletes the layer. **WARNING: also deletes every entity on that layer.** Undoable.
- #### `rename_layer`
- Args: `layerName` (existing, matched case-insensitively), `newName` (applied as-is, case-sensitive, must be unique). Undoable.
- #### `set_layer_order`
- Args: `layerName` (matched case-insensitively), `direction` (`up` | `down`). Moves the layer one step in the stack (swaps with its neighbor). Lower index draws behind, higher draws in front. Undoable.
- #### `set_entity_layer`
- Args: `entityId`, `layerName`. Moves an entity onto a different layer. The destination layer must exist on the **entity's parent composite** (so `list_layers` while viewing that parent). `layerName` matched case-insensitively. The entity lands at the front of the destination layer; use `set_z_index` to fine-tune its position within the layer. Undoable.
- ### Visual
- #### `screenshot`
- Args: `mode` (`whole` | `region`, default `whole`); for `region` also `x`, `y`, `width`, `height` (world units). Returns a PNG as MCP **image content**.
- - `whole` — all entities regardless of viewport (recommended for verifying a scene). Frames the union of the root's direct children's bounding boxes.
- - `region` — a world-space rectangle (`x`, `y` is the corner; good for inspecting a specific area).
- - Screenshots currently do **not** render lights (known limitation).
- - Huge scenes/regions are capped to the GPU's max texture size per side, preserving aspect.
- ---
- ## Edge cases & gotchas
- ### Primitives: width/height are NOT the size
- A color primitive's visual size is its **polygon vertices** (`PolygonShapeComponent`), not `DimensionsComponent.width/height` — those are a derived bounding box. Consequences:
- - `update_transform` **refuses** `width`/`height` on primitives (the basic panel disables them for primitives, images, sprites, etc. — only label/composite/9-patch allow width/height). This is by design, not a bug.
- - At **creation** time, `create_entity` with `type: "primitive"` does accept `width`/`height` and builds the rect polygon from them (`PolygonShapeVO.createRect(width, height)`).
- - To **resize an existing primitive**, use `scaleX`/`scaleY` (via `update_transform`), or edit the polygon shape (`update_component` with `componentKey: "polygon"` controls `verticesCount`/`openPath`, not direct coordinates). For an exact new rectangle size, recreate the primitive.
- ### pixelsPerWU dominates coordinate choice
- `x`, `y`, `width`, `height` are world units. With `pixelsPerWU = 100`, an entity at `x = 300` is 300 world units from origin — possibly far off-screen if the scene is small. Always read `pixelsPerWU` (`get_scene_settings` / `get_asset_dimensions`) first, and compute placement from asset **world** dimensions (`worldWidth = pixelWidth / pixelsPerWU`).
- ### Colors
- Color fields (`tint`, `color`, `ambientColor`, `directionalColor`) accept any of:
- - `"r,g,b,a"` (e.g. `"1,0,0,1"`)
- - a JSON array `[r,g,b,a]`
- - `"#RRGGBBAA"` hex (e.g. `"#FF0000FF"`)
- ### Label align is case-insensitive
- `update_component` (`label`, `align`) matches the allowed names case-insensitively: `"top left"`, `"Center"`, `"BOTTOM RIGHT"` all work. Allowed values: `Top Left, Top, Top Right, Left, Center, Right, Bottom Left, Bottom, Bottom Right`.
- ### Layers are per-composite and (mostly) case-sensitive
- Each composite — including the scene root — has its **own** layer list; a layer named `Default` at the root is a different list from one inside a composite. To move an entity to a layer, that layer must exist on the **entity's parent** (call `list_layers` while viewing the parent). Layer names are stored case-sensitively (by hash), so `Default` ≠ `default` ≠ `DEFAULT` as far as the editor is concerned — but the layer tools resolve names **case-insensitively** so you won't trip on casing when referencing an existing layer. `create_layer`/`rename_layer` use the exact string you pass, so decide the casing deliberately. `delete_layer` deletes the layer *and* every entity on it.
- ### Building a composite correctly (READ THIS — the #1 mistake)
- A composite has its own local coordinate space, and by default `automaticResize = true`: **the composite's size and origin are recomputed from its children.** You do **not** know a composite's final position/size until its children exist. The first child anchors the local origin. This dictates the workflow.
- **The correct sequence — build the group in local space, then place the whole group:**
- 1. **Create the composite** (`create_entity` type `composite`) at `(0, 0)`. Its position is provisional — you set the real one in step 4.
- 2. **Add the anchor child first.** The first child defines the origin: it lands at local `(0, 0)` no matter what `x`/`y` you pass. So make the first child the object you want *at the group's origin* (e.g. the bottom-left tile of a wall, the base of a structure). Passing `(0,0)` for it is honest and clearest.
- 3. **Add the rest with `parentUniqueId`, in LOCAL coordinates relative to that anchor.** A child at local `(2, 1)` is 2 units right / 1 down *from the anchor*. Design the group as its own little scene whose origin is the anchor. Pick the anchor so the other locals are simple (usually the group's bottom-left, giving all-positive locals).
- 4. **Position the composite in its parent.** Now `automaticResize` has computed the composite's size. `update_transform` the composite's `(x, y)` to drop the finished group where it belongs. Everything inside moves rigidly — you place the container **once**, never the children.
- **Concrete example — a wall row that belongs at world y=5:** create composite; add wall segments at local `(0,0), (1,0), (2,0), …` (all `y=0`, the row's baseline); then `update_transform` the composite to `(0, 5)`. Result: the row sits at world y=5. Do **not** instead give the segments `y=5` and leave the composite at `(0,0)` — that puts world coordinates into local space and makes the composite's position meaningless.
- **Two failure modes to never repeat:**
- - **World coords as local coords + composite left at origin.** Semantically wrong even when it happens to render: the composite's position no longer means anything, and the group can't be moved as a unit.
- - **"Fixing" the first child (or any child) after the fact.** The first child sitting at the origin is *correct* — it defines the local space. Deleting/recreating it, or `update_transform`-ing a single child in an `automaticResize` composite, re-derives the bounding box and scrambles the group. Build it right in one pass; don't post-patch individual children.
- **Before concluding a child is misplaced or missing, check z-index between composites** (see *Z-index* below). Sibling composites draw in composite-creation order — an entire composite (and everything in it) can be hidden behind another composite. A "missing" object is usually a z-order problem, not a position problem. Verify with a `region` screenshot of where it *should* be before touching anything.
- **Do not disable `automaticResize`.** Leaving it on (the default) is how composites are meant to work — it is what lets the container size itself to its children so you can then position it. Turning it off is only for rare special effects, never as a workaround for a placement you got wrong.
- **Nesting / other rules:**
- - The parent must be a **direct child of the current viewing entity** (normally the scene root). The editor's enter-composite flow only supports entering one level at a time. If you get *"parent composite must be a direct child of the current viewing entity; double-click its container in the editor to enter it first"*, enter the outer composite in the editor UI, then target the inner composite's uniqueId.
- - Passing a non-composite uniqueId (an entity with no children slot) errors with *"parent is not a composite/container"*.
- - The enter/exit happens within one render frame (no visible camera jump) and is **not** pushed to the undo stack — only the entity creation is undoable.
- ### Z-index is per-layer and absolute
- `set_z_index` sets an absolute integer scoped to the entity's **layer**. The runtime re-linearizes z-indices, so don't try to compute "relative" offsets — just set the order you want (e.g. background=0, mid=5, foreground=10). Retrieve current values from `list_entities`.
- **Sibling composites draw in their own z-order, and it carries their whole subtree.** Among children of the same parent (including the top-level composites under the root), z-index follows **creation order** by default — created earlier = drawn behind. So a composite created before another draws *entirely* behind it, and so does every child inside it. Consequence: an object placed at exactly the right coordinates can be completely hidden because its composite sits behind a later one (e.g. `props` created before `path` → the rune circle in `props` is covered by the path tiles). **When something "isn't there," suspect z-order first**: check the composites' `zIndex` in `list_entities`, and `set_z_index` the composite (not the child) to bring the whole group forward/back. Create composites in back-to-front order (background first), or fix the order afterward with `set_z_index`. Do not go hunting for a "wrong position" or delete/recreate anything until you've ruled out z-order.
- ### Component edits are panel-validated
- Every `add_component` / `update_component` / `remove_component` / `update_transform` / `update_scene_settings` drives the real UI panel off-stage and runs its VisUI validators. If a value is rejected, the error message is the panel's. Use `get_editable_components` to discover what's allowed for a given entity before editing. Never assume a field exists for a type.
- ### Bulk operations
- `create_entities` and `delete_entities` process entries sequentially and return per-entry results; a failure in one entry does **not** abort the others. Check the returned array for partial failures.
- ### Undoability
- `create_entity`/`create_entities`, `update_transform`, `update_component`, `add_component`, `remove_component`, `set_z_index`, `delete_entity`/`delete_entities`, `update_scene_settings`, `create_layer`, `delete_layer`, `rename_layer`, `set_layer_order`, `set_entity_layer` are all undoable in the editor (Ctrl+Z). Composite enter/exit for creation is intentionally not on the undo stack. `create_shader` writes resource files (not a scene edit).
- ### Visual verification is the user's job
- Never judge a screenshot as "looks good" on the user's behalf. Capture the screenshot, hand it over, and let the user decide. Your responsibility is correct, validated structure and correct coordinates/scale.
- ---
- ## Recommended workflow: design a scene from scratch
- 1. `open_scene` (or confirm the current scene) → `get_scene_settings` (note `pixelsPerWU`).
- 2. `list_assets` → `get_asset_dimensions` (world sizes) → `get_asset_preview` for the regions you'll use (see them).
- 3. Plan placement in world units using `worldWidth`/`worldHeight` (tile spacing = region world size; positions relative to origin). Group related entities into composites (e.g. `ground`, `path`, `wall`, `props`) — it keeps the scene tree navigable and lets you order/move whole groups at once. **Create composites back-to-front** (background group first) so their creation-order z-index already matches the draw order you want.
- 4. For each group: create the composite; add the **anchor child first** (it lands at the origin), then `create_entities` (bulk) with `parentUniqueId` and the rest in **local** coordinates relative to that anchor; then `update_transform` the composite to its final position (see *Building a composite correctly*). Capture the returned `uniqueId`s.
- 5. If any group is hidden or draws in the wrong order, `set_z_index` the **composite** (not its children) to reorder whole groups background→foreground. Rule out z-order before ever suspecting a wrong position.
- 6. Add components as needed: `get_editable_components` → `add_component` → `update_component`. **Place each light inside the composite/hierarchy of the object it illuminates, at that object's position** — never in a standalone lights group.
- 7. `screenshot` (mode `whole`) → return it to the user for visual verification.
- 8. Iterate based on user feedback; `save_project` when satisfied.
- If something is rejected, read the error — it reflects the editor's real validation. Don't retry the same invalid value. And never delete/recreate or post-`update_transform` a composite's children to "fix" placement — build each group right in one pass, then move only the composite.
README.md · README · 117 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- 
- [](https://github.com/rednblackgames/HyperLap2D/actions?query=workflow%3A%22SNAPSHOT+Build%22)
- [](https://github.com/rednblackgames/HyperLap2D/releases)
- [](https://github.com/rednblackgames/HyperLap2D/actions?query=workflow%3A%22SNAPSHOT+Build%22)
- [](https://discord.gg/p69rPNF)
- # HyperLap2D
- HyperLap2D is a powerful, platform-independent, visual editor for complex 2D worlds and scenes.
- An engine-oriented alternative for building games free from any design constraints.
- Open Source ❤️
- [](https://www.youtube.com/watch?v=VUJd7fq_J7c)
- ### Project Status
- Currently, HyperLap2D is in Alpha stage. Many breaking changes could happen update after update without backwards compatibility. Therefore, please always check our [changelog](https://github.com/rednblackgames/HyperLap2D/tree/master/CHANGES) before updating.
- ### Download
- | Release | Snapshot |
- | ------- | -------- |
- | [GitHub Releases](https://github.com/rednblackgames/HyperLap2D/releases) | [GitHub Actions](https://github.com/rednblackgames/HyperLap2D/actions?query=workflow%3A%22SNAPSHOT+Build%22) |
- ### Features
- - Images and Sprite Animations
- - Box2D Physics World
- - Dynamic Lights
- - [Spine support](https://github.com/rednblackgames/h2d-libgdx-spine-extension)
- - Particle Effects
- - Grouping complex objects into library items
- - Import, Export and Share your compositions
- - Live Preview
- - Tiled Maps
- - Built in 9-patch editor
- - Actions Node Editor
- - [Plugins](https://hyperlap2d.rednblack.games/wiki/plugins/)
- - Open JSON output
- ### Getting Started
- - [HyperLap2D Website](https://hyperlap2d.rednblack.games)
- - [Official Wiki](https://hyperlap2d.rednblack.games/wiki)
- - [HyperLab](https://hyperlab.rednblack.games)
- ### Runtime
- Currently, HyperLap2D is mainly developed for [libGDX](https://github.com/libgdx/libgdx), but it can easily be integrated into any software thanks to its open JSON output format.
- Check out the libGDX runtime [README](https://github.com/rednblackgames/hyperlap2d-runtime-libgdx) to start integrating HyperLap2D's project into your game.
- See our [Wiki](https://hyperlap2d.rednblack.games/wiki/hyperlap2d/14-json-export-format/), if you want to learn more about the output format.
- ### Issues
- Have you found a bug or unexpected behavior? Don't panic! Search for [known issues](https://github.com/rednblackgames/HyperLap2D/issues) or feel free to open a new one. Your feedback is important, please try to be as detailed as possible :)
- ### Contributing
- We need your help! HyperLap2D is a very large and complex project, if you have some cool addition or bug fix don't hesitate to create a [Pull Request](https://github.com/rednblackgames/HyperLap2D/pulls). Any contribution, big or small, is always well received.
- #### Building from source
- HyperLap2D is developed using IntelliJ IDEA. Needs `Java 25`.
- 1. Fork this repository
- 2. Clone with `--recurse-submodules` flag
- 3. Open the main `build.gradle`, which you can find in the root directory
- 4. Run `runHyperLap2D` gradle task
- 5. If build fails: `File → Invalidate Caches / Restart`
- ### License
- HyperLap2D Editor is licensed under the GNU Public License, Version 3. You may wish to read [HyperLap2D libGDX Runtime](https://github.com/rednblackgames/hyperlap2d-runtime-libgdx) License and [Spine Extension](https://github.com/rednblackgames/h2d-libgdx-spine-extension) License.
- ```
- HyperLap2D Editor
- Copyright (C) 2020 Francesco Marongiu
- This program is free software: you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation, either version 3 of the License, or
- (at your option) any later version.
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
- You should have received a copy of the GNU General Public License
- along with this program. If not, see <http://www.gnu.org/licenses/>.
- ```
- #### Overlap2D
- HyperLap2D is a fork of [Overlap2D](https://github.com/UnderwaterApps/overlap2d). A very special thanks to UnderwaterApps's Team and all of their Contributors for creating it, as without, HyperLap2D could never be possible.
- Check out original: [`OVERLAP2D-AUTHORS`](https://github.com/rednblackgames/HyperLap2D/blob/master/OVERLAP2D-AUTHORS) and [`OVERLAP2D-CONTRIBUTORS`](https://github.com/rednblackgames/HyperLap2D/blob/master/OVERLAP2D-CONTRIBUTORS)
- _Overlap2D_ was licensed under `Apache 2.0`
- ```
- Copyright 2015 Underwater Apps LLC
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
- http://www.apache.org/licenses/LICENSE-2.0
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.