Skip to content
Back to search

hyperlap2d-mcp

SkillWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rednblackgames--hyperlap2d/badge.svg)](/listings/rednblackgames--hyperlap2d)

HTML

<a href="/listings/rednblackgames--hyperlap2d"><img src="/api/listings/rednblackgames--hyperlap2d/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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)

  1. ---
  2. name: hyperlap2d-mcp
  3. 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.
  4. ---
  5. # HyperLap2D MCP Server — Tool Guide
  6. 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.
  7. ## Prerequisites & connection
  8. 1. The editor is running (`./gradlew runHyperLap2D`) with a project open and a scene loaded.
  9. 2. **Settings → Plugins → "MCP Server"** is enabled (and the port set). The server starts/stops live on toggle.
  10. 3. The MCP client connects to `http://127.0.0.1:<port>/mcp` (Streamable HTTP). Configure it like:
  11. ```json
  12. { "mcpServers": { "hyperlap2d": { "url": "http://127.0.0.1:8765/mcp" } } }
  13. ```
  14. 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.
  15. 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.
  16. ## Core model (read this before placing anything)
  17. - **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.
  18. - **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.
  19. - **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.
  20. - **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.
  21. - **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.
  22. - **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.
  23. - **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.
  24. - **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).
  25. - **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.
  26. ## Golden rules for scene authoring
  27. 1. `get_scene_settings` → note `pixelsPerWU`.
  28. 2. `list_assets` → know what's available.
  29. 3. `get_asset_dimensions` → learn each region's world size.
  30. 4. `get_asset_preview` → *see* the assets you plan to use.
  31. 5. `create_entity` / `create_entities` at correct world coordinates (computed from pixelsPerWU and asset world sizes).
  32. 6. `set_z_index` to order layers/depth.
  33. 7. `screenshot` (mode `whole` or `region`) to let the user verify.
  34. Do not place entities blindly; do not invent asset semantics. The user judges all visual results — your job is correct, validated structure.
  35. ---
  36. ## Tool reference
  37. 28 tools. Grouped by purpose.
  38. ### Discovery (read-only)
  39. #### `list_scenes`
  40. No args. Returns `[{ "name": ... }]` — all scenes in the open project.
  41. #### `list_entities`
  42. No args. Returns a flat array of every entity in the current scene:
  43. `{ uniqueId, parentId, name, typeId, type, depth, zIndex, layer }`
  44. - `uniqueId` — the stable id you pass to all mutation tools.
  45. - `parentId` — null for direct children of the scene root; otherwise the parent composite's uniqueId. Use with `depth` to rebuild the tree.
  46. - `type` — display name (covers core + Spine/Talos/TinyVG).
  47. - `zIndex`, `layer` — the per-layer z-index and layer name (mirror of `set_z_index`).
  48. #### `list_assets`
  49. No args. Returns loaded project assets grouped by category:
  50. `imageRegion`, `ninePatchRegion`, `spineAnimation`, `spriteAnimation`, `particleEffect`, `talosEffect`, `font`, `tinyvg`, `shader`.
  51. Use region names for `create_entity` (image/9patch) and shader names for `update_component`/`update_scene_settings`.
  52. #### `get_asset_dimensions`
  53. 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.
  54. #### `get_asset_preview`
  55. 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.
  56. #### `get_scene_settings`
  57. 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.
  58. #### `get_editable_components`
  59. 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.
  60. #### `list_actions`
  61. 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.)
  62. ### Mutation (validated, undoable unless noted)
  63. #### `create_entity`
  64. Args: `type` (required), `name`, `x`, `y`, `width`, `height`, `fontFamily`, `fontSize`, `lightType`, `parentUniqueId`, `layer`.
  65. - `type`: `image | spriteAnimation | spineAnimation | libraryItem | 9patch | tinyvg | particle | talos | primitive | composite | label | light`.
  66. - Name-based types (`image`, `spriteAnimation`, `spineAnimation`, `libraryItem`, `9patch`, `tinyvg`, `particle`, `talos`) require `name` from `list_assets`.
  67. - `primitive`: `width`/`height` (default 100) define the rect at creation.
  68. - `label`: optional `fontFamily` (must be a loaded font) / `fontSize` (default 20).
  69. - `light`: `lightType` `POINT` (default) or `CONE`.
  70. - `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.
  71. - `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.
  72. - Returns the new entity's `uniqueId`. Creation is undoable (Ctrl+Z).
  73. #### `create_entities` (bulk)
  74. 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.
  75. #### `update_transform`
  76. 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).
  77. - **`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).
  78. #### `update_component`
  79. 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:
  80. | componentKey | applies to | fields |
  81. |---|---|---|
  82. | `basic` | all entities | x, y, width, height, scaleX, scaleY, rotation, flipX, flipY, id, tint |
  83. | `label` | label entities | text, fontFamily, bitmapFont, fontSize, align, wrap, mono |
  84. | `particle` | particle effects | matrixTransform, autoStart |
  85. | `image` | images | renderMode, spriteType |
  86. | `composite` | composites | scissorsEnabled, renderToFBO, automaticResize |
  87. | `sprite` | sprite animations | fps, animation, playMode |
  88. | `spine` | spine animations | animation, skin |
  89. | `talos` | talos effects | matrixTransform, autoStart |
  90. | `lightItem` | light entities | type, rayCount, radius, angle, distance, direction, intensity, height, softnessLength, falloff, isStatic, isXRay, isSoft, isActive |
  91. | `shader` | entities with a Shader component | shaderName, renderingLayer |
  92. | `physics` | entities with Physics | mass, density, friction, restitution, damping, angularDamping, gravityScale, height, centerOfMassX, centerOfMassY, rotationalInertia, bodyType, shapeType, allowSleep, awake, bullet, sensor, fineBoundBox, fixedRotation |
  93. | `light` | entities with a Light component | rays, distance, intensity, constantFalloff, linearFalloff, quadraticFalloff, softnessLength, height, direction, isStatic, isXRay, isSoft, isActive, color |
  94. | `circle` | entities with Circle Shape | radius |
  95. | `polygon` | entities with Polygon Shape | verticesCount, openPath |
  96. | `sensor` | entities with Sensor | sensorTop/Bottom/Left/Right, spanPercentTop/Bottom/Left/Right, heightPercentTop/Bottom, widthPercentLeft/Right |
  97. | `layout` | entities with Layout | leftMargin/rightMargin/bottomMargin/topMargin, horizontalBias/verticalBias, leftEnabled/rightEnabled/bottomEnabled/topEnabled, leftTarget/rightTarget/bottomTarget/topTarget, leftSide/rightSide/bottomSide/topSide, matchWidth/matchHeight |
  98. For shape/physics/light/etc. components, the entity must already have that component — `add_component` it first (or check `get_editable_components`).
  99. #### `add_component`
  100. 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.
  101. #### `remove_component`
  102. Args: `entityId`, `componentKey` (same keys). Only the removable components above. Undoable.
  103. #### `set_z_index`
  104. 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`).
  105. #### `delete_entity`
  106. Args: `entityId`. Selects then runs the standard delete command. Undoable.
  107. #### `delete_entities` (bulk)
  108. 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.
  109. #### `open_scene`
  110. 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.
  111. #### `update_scene_settings`
  112. 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.
  113. #### `create_shader`
  114. 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.
  115. #### `save_project`
  116. No args. Saves the current project (all scenes and assets) to disk.
  117. ### Layers
  118. 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.
  119. #### `list_layers`
  120. 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.
  121. #### `create_layer`
  122. 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.
  123. #### `delete_layer`
  124. Args: `layerName` (matched case-insensitively). Deletes the layer. **WARNING: also deletes every entity on that layer.** Undoable.
  125. #### `rename_layer`
  126. Args: `layerName` (existing, matched case-insensitively), `newName` (applied as-is, case-sensitive, must be unique). Undoable.
  127. #### `set_layer_order`
  128. 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.
  129. #### `set_entity_layer`
  130. 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.
  131. ### Visual
  132. #### `screenshot`
  133. Args: `mode` (`whole` | `region`, default `whole`); for `region` also `x`, `y`, `width`, `height` (world units). Returns a PNG as MCP **image content**.
  134. - `whole` — all entities regardless of viewport (recommended for verifying a scene). Frames the union of the root's direct children's bounding boxes.
  135. - `region` — a world-space rectangle (`x`, `y` is the corner; good for inspecting a specific area).
  136. - Screenshots currently do **not** render lights (known limitation).
  137. - Huge scenes/regions are capped to the GPU's max texture size per side, preserving aspect.
  138. ---
  139. ## Edge cases & gotchas
  140. ### Primitives: width/height are NOT the size
  141. A color primitive's visual size is its **polygon vertices** (`PolygonShapeComponent`), not `DimensionsComponent.width/height` — those are a derived bounding box. Consequences:
  142. - `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.
  143. - At **creation** time, `create_entity` with `type: "primitive"` does accept `width`/`height` and builds the rect polygon from them (`PolygonShapeVO.createRect(width, height)`).
  144. - 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.
  145. ### pixelsPerWU dominates coordinate choice
  146. `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`).
  147. ### Colors
  148. Color fields (`tint`, `color`, `ambientColor`, `directionalColor`) accept any of:
  149. - `"r,g,b,a"` (e.g. `"1,0,0,1"`)
  150. - a JSON array `[r,g,b,a]`
  151. - `"#RRGGBBAA"` hex (e.g. `"#FF0000FF"`)
  152. ### Label align is case-insensitive
  153. `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`.
  154. ### Layers are per-composite and (mostly) case-sensitive
  155. 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.
  156. ### Building a composite correctly (READ THIS — the #1 mistake)
  157. 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.
  158. **The correct sequence — build the group in local space, then place the whole group:**
  159. 1. **Create the composite** (`create_entity` type `composite`) at `(0, 0)`. Its position is provisional — you set the real one in step 4.
  160. 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.
  161. 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).
  162. 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.
  163. **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.
  164. **Two failure modes to never repeat:**
  165. - **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.
  166. - **"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.
  167. **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.
  168. **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.
  169. **Nesting / other rules:**
  170. - 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.
  171. - Passing a non-composite uniqueId (an entity with no children slot) errors with *"parent is not a composite/container"*.
  172. - 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.
  173. ### Z-index is per-layer and absolute
  174. `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`.
  175. **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.
  176. ### Component edits are panel-validated
  177. 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.
  178. ### Bulk operations
  179. `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.
  180. ### Undoability
  181. `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).
  182. ### Visual verification is the user's job
  183. 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.
  184. ---
  185. ## Recommended workflow: design a scene from scratch
  186. 1. `open_scene` (or confirm the current scene) → `get_scene_settings` (note `pixelsPerWU`).
  187. 2. `list_assets` → `get_asset_dimensions` (world sizes) → `get_asset_preview` for the regions you'll use (see them).
  188. 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.
  189. 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.
  190. 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.
  191. 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.
  192. 7. `screenshot` (mode `whole`) → return it to the user for visual verification.
  193. 8. Iterate based on user feedback; `save_project` when satisfied.
  194. 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)

  1. ![Logo](https://raw.githubusercontent.com/rednblackgames/HyperLap2D/master/icons/HyperLap2D.png)
  2. [![GitHub Actions Build Status](https://img.shields.io/github/actions/workflow/status/rednblackgames/HyperLap2D/snapshot.yml?branch=master&label=GitHub%20Actions)](https://github.com/rednblackgames/HyperLap2D/actions?query=workflow%3A%22SNAPSHOT+Build%22)
  3. [![release](https://img.shields.io/github/v/release/rednblackgames/HyperLap2D)](https://github.com/rednblackgames/HyperLap2D/releases)
  4. [![snapshot](https://img.shields.io/maven-metadata/v?label=snapshot&metadataUrl=https%3A%2F%2Fcentral.sonatype.com%2Frepository%2Fmaven-snapshots%2Fgames%2Frednblack%2Fhyperlap2d%2Fruntime-libgdx%2Fmaven-metadata.xml)](https://github.com/rednblackgames/HyperLap2D/actions?query=workflow%3A%22SNAPSHOT+Build%22)
  5. [![Discord](https://img.shields.io/discord/740954840259362826?label=Discord&logo=discord)](https://discord.gg/p69rPNF)
  6. # HyperLap2D
  7. HyperLap2D is a powerful, platform-independent, visual editor for complex 2D worlds and scenes.
  8. An engine-oriented alternative for building games free from any design constraints.
  9. Open Source ❤️
  10. [![YouTube Video](https://user-images.githubusercontent.com/5543339/110386916-36880900-8061-11eb-872a-f04d2a3a28b9.png)](https://www.youtube.com/watch?v=VUJd7fq_J7c)
  11. ### Project Status
  12. 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.
  13. ### Download
  14. | Release | Snapshot |
  15. | ------- | -------- |
  16. | [GitHub Releases](https://github.com/rednblackgames/HyperLap2D/releases) | [GitHub Actions](https://github.com/rednblackgames/HyperLap2D/actions?query=workflow%3A%22SNAPSHOT+Build%22) |
  17. ### Features
  18. - Images and Sprite Animations
  19. - Box2D Physics World
  20. - Dynamic Lights
  21. - [Spine support](https://github.com/rednblackgames/h2d-libgdx-spine-extension)
  22. - Particle Effects
  23. - Grouping complex objects into library items
  24. - Import, Export and Share your compositions
  25. - Live Preview
  26. - Tiled Maps
  27. - Built in 9-patch editor
  28. - Actions Node Editor
  29. - [Plugins](https://hyperlap2d.rednblack.games/wiki/plugins/)
  30. - Open JSON output
  31. ### Getting Started
  32. - [HyperLap2D Website](https://hyperlap2d.rednblack.games)
  33. - [Official Wiki](https://hyperlap2d.rednblack.games/wiki)
  34. - [HyperLab](https://hyperlab.rednblack.games)
  35. ### Runtime
  36. 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.
  37. Check out the libGDX runtime [README](https://github.com/rednblackgames/hyperlap2d-runtime-libgdx) to start integrating HyperLap2D's project into your game.
  38. See our [Wiki](https://hyperlap2d.rednblack.games/wiki/hyperlap2d/14-json-export-format/), if you want to learn more about the output format.
  39. ### Issues
  40. 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 :)
  41. ### Contributing
  42. 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.
  43. #### Building from source
  44. HyperLap2D is developed using IntelliJ IDEA. Needs `Java 25`.
  45. 1. Fork this repository
  46. 2. Clone with `--recurse-submodules` flag
  47. 3. Open the main `build.gradle`, which you can find in the root directory
  48. 4. Run `runHyperLap2D` gradle task
  49. 5. If build fails: `File → Invalidate Caches / Restart`
  50. ### License
  51. 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.
  52. ```
  53. HyperLap2D Editor
  54. Copyright (C) 2020 Francesco Marongiu
  55. This program is free software: you can redistribute it and/or modify
  56. it under the terms of the GNU General Public License as published by
  57. the Free Software Foundation, either version 3 of the License, or
  58. (at your option) any later version.
  59. This program is distributed in the hope that it will be useful,
  60. but WITHOUT ANY WARRANTY; without even the implied warranty of
  61. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  62. GNU General Public License for more details.
  63. You should have received a copy of the GNU General Public License
  64. along with this program. If not, see <http://www.gnu.org/licenses/>.
  65. ```
  66. #### Overlap2D
  67. 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.
  68. 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)
  69. _Overlap2D_ was licensed under `Apache 2.0`
  70. ```
  71. Copyright 2015 Underwater Apps LLC
  72. Licensed under the Apache License, Version 2.0 (the "License");
  73. you may not use this file except in compliance with the License.
  74. You may obtain a copy of the License at
  75. http://www.apache.org/licenses/LICENSE-2.0
  76. Unless required by applicable law or agreed to in writing, software
  77. distributed under the License is distributed on an "AS IS" BASIS,
  78. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  79. See the License for the specific language governing permissions and
  80. limitations under the License.
  81. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.