A fast, browser-based command builder for Minecraft Java Edition block_display entities.
Minecraft Block Display Generator is a focused web tool for players, map makers, datapack authors, command creators, and server builders who want to create minecraft:block_display entities without manually assembling long SNBT structures or calculating quaternion rotation values. Display entities are extremely flexible because they allow a block model to be positioned, scaled, translated, and rotated independently from a normal placed block. That flexibility is useful for custom props, decorative builds, animated scenes, adventure maps, visual effects, custom interfaces, and many other command-driven creations.
The project is intentionally designed as a quick generator rather than a full 3D scene editor. The main workflow is visible immediately when the page loads: choose a block, configure its block states, set position and transformation values, inspect the live preview, and copy a generated command. The interface converts a simple axis and degree value into the quaternion data used by the display transformation. Anchor presets also calculate centering offsets automatically, which makes common scaling workflows much faster.
The entire application is static and runs in the browser. It is suitable for GitHub Pages and similar static hosting services. No build process is required for deployment, and the production files can be served directly from the repository root.
The generator creates three related Minecraft commands from one configuration. The Summon command creates a new minecraft:block_display entity. The Update command uses /data merge entity to apply the current block state and transformation to the nearest display carrying the generated tag. The Remove command uses that same tag to delete the matching display entities when a test object is no longer needed.
The tool includes a searchable list of common Minecraft blocks while still accepting a manually entered namespaced block ID. For blocks with familiar state patterns, the page creates dedicated controls. Examples include stair facing, half and shape; slab type; log axis; door and trapdoor state; leaf persistence; snow layers; farmland moisture; and crop age. A custom block-state field is also available for state key/value pairs that are not covered by the presets.
Transformation controls include position, three-axis scale, translation, rotation, and anchor selection. Rotation can be entered as a familiar degree value around X, Y, Z, or a custom axis. Internally, the generator normalizes the axis and converts the axis-angle rotation into a quaternion. The resulting values are serialized into the left_rotation array used by the generated transformation compound.
The live preview is intended to make transforms easier to understand before copying a command. It visualizes scale, rotation, and translation and also displays the calculated quaternion and effective translation values. Validation messages are shown inline, so invalid block IDs, coordinates, scale values, entity tags, or rotation axes can be corrected without modal dialogs.
- Open the generator in a modern browser and select the Minecraft Java version you are targeting.
- Enter a block ID such as
minecraft:stone,minecraft:oak_stairs, or another valid namespaced block identifier. Common choices appear as browser suggestions while typing. - Configure any block-state fields that appear. For an oak stair, for example, you can choose facing, half, shape, and waterlogged values. Extra properties can be entered in the custom block states field with syntax such as
facing=east,half=bottom. - Enter the entity position. Relative coordinates such as
~ ~1 ~-2, local coordinates beginning with^, and absolute numeric coordinates are accepted by the validator. - Set Scale X, Y, and Z. The ratio lock is enabled initially so changing one scale field changes the other two. Turn the lock off when non-uniform scaling is required.
- Choose a rotation axis and enter an angle in degrees. Select Custom to enter an arbitrary X/Y/Z axis vector. The page converts this human-friendly input into the quaternion used by the command.
- Choose an anchor preset. Center, bottom center, and top center automatically add translation offsets based on the current scale. Select the corner or custom option when you want direct control over translation.
- Add any additional translation offset and review the visual transform preview.
- Keep the generated entity tag or replace it with your own valid tag. The tag connects the Summon, Update, and Remove workflow.
- Copy the Summon command into Minecraft. Use the Update command after changing values, and use the Remove command to delete displays carrying the selected tag.
The primary output format is plain Minecraft Java Edition command text using SNBT entity data. The generated Summon output follows the general form /summon minecraft:block_display <position> {...}. The Update output uses /data merge entity, and the cleanup output uses /kill with a type and tag selector.
Block IDs are accepted with or without the minecraft: namespace. Unqualified IDs are normalized to the Minecraft namespace. Block states are represented as string properties inside the block_state compound. Position supports absolute numeric coordinates, relative ~ coordinates, and local ^ coordinates. Transformation vectors are serialized as float arrays, including translation, scale, and quaternion rotation.
The project does not require uploaded source files. Configuration is entered directly in the browser and the result is copied as text. This keeps the workflow fast for command blocks, chat commands, datapack functions, and other Minecraft command workflows.
The project uses semantic HTML, responsive CSS, and dependency-free JavaScript ES modules. js/block-display.js contains deterministic command logic so the mathematical behavior can be tested separately from the user interface. The module validates configuration, normalizes block IDs, converts axis-angle rotations to normalized quaternions, computes anchor offsets, serializes block-state properties, and produces the three command strings.
For an axis vector (x, y, z) and angle in degrees, the module first calculates the vector length and normalizes the axis. The angle is converted to radians and divided by two. Quaternion X, Y, and Z are the normalized axis components multiplied by sin(angle / 2), while quaternion W is cos(angle / 2). Values are rounded to six decimal places for compact, stable command output.
The center anchor uses (1 - scale) / 2 on each dimension, which keeps a scaled unit block centered inside its original one-block space. Bottom-center applies the centering offset on X and Z while leaving Y at the bottom. Top-center centers X and Z and shifts Y by 1 - scaleY.
The visual preview uses CSS 3D transforms and does not download a 3D engine. It is deliberately lightweight: its purpose is to show the direction and relative effect of the current transformation quickly. The generated command remains the authoritative output of the tool.
The Progressive Web App layer consists of manifest.json, installable PNG icons, an SVG icon, and sw.js. The Service Worker pre-caches the complete runtime application shell during installation. Requests use a network-first strategy: the worker attempts the network first, stores successful responses in the cache, and falls back to cached content when the network request fails. This keeps repeat visits fresh while retaining offline resilience.
Automated tests use Node.js's built-in node:test runner and require no third-party test framework. The suite checks quaternion math, anchor offsets, validation, command generation, SEO metadata, GitHub link attributes, responsive CSS markers, PWA metadata, cache behavior, icon presence, repository configuration, and README requirements.
block-display-generator/
├── index.html
├── manifest.json
├── sw.js
├── repo.config.json
├── package.json
├── LICENSE
├── README.md
├── assets/
│ └── icons/
│ ├── icon.svg
│ ├── icon-192.png
│ └── icon-512.png
├── css/
│ └── styles.css
├── js/
│ ├── app.js
│ └── block-display.js
├── tests/
│ ├── artifact-contract.test.mjs
│ └── block-display.test.mjs
└── docs/
└── superpowers/
├── plans/
└── specs/
index.html contains the page structure, SEO metadata, required integration placeholders, generator controls, preview, and command output areas. css/styles.css provides responsive desktop and mobile layouts. js/app.js connects browser controls to the command engine and updates the live preview. js/block-display.js contains the reusable transformation and command functions. The PWA files live at repository root so GitHub Pages can serve them with a scope that covers the application.
No production build is required. The repository root is already the deployable static site. For GitHub Pages, create the public repository named block-display-generator, push these files to the main branch, and enable GitHub Pages from the repository settings using the root of the main branch as the publishing source. The canonical production address is:
https://yeshan-jun.github.io/block-display-generator/
For local testing, any static HTTP server can be used. One simple option with Python is:
python3 -m http.server 8000Then open http://localhost:8000/. Service Workers require an HTTP or HTTPS origin, so serving the project locally is the correct way to test installation, caching, and offline fallback behavior. You can run the automated checks with:
npm testThe project has no npm run build requirement. package.json exists only to provide a convenient test command and module configuration.
Repository name: block-display-generator
Repository URL: https://github.com/yeshan-jun/block-display-generator
GitHub Pages URL: https://yeshan-jun.github.io/block-display-generator/
The included repo.config.json records the intended repository name, English description, public visibility, homepage, focused GitHub topics, main default branch, README creation setting, and source/pages stack. The repository is designed to contain the complete source and the exact files served by GitHub Pages, which keeps deployment easy to inspect and reproduce.
The generator performs its command calculations in the browser. Block IDs, transformation values, coordinates, entity tags, and generated commands are processed by local JavaScript in the page. The core generator does not require an account, API key, database, or command-generation server. The PWA cache contains the static application assets required to load the interface and logic during an offline fallback.
If analytics or other external services are added later through the reserved integration placeholders, their behavior and privacy implications should be documented separately according to the service that is actually configured. The base project itself does not need such a service to generate commands.
This project is released under the MIT License.
The full MIT license text is included in the LICENSE file. You may use, modify, distribute, and publish the project under the terms described there while retaining the required copyright and license notice.
- Minecraft Snapshot 23w06a — Mojang introduced display entities and documented transformation fields:
https://www.minecraft.net/en-us/article/minecraft-snapshot-23w06a - Minecraft Java Edition 1.19.4 release notes — official release containing display entities:
https://www.minecraft.net/en-us/article/minecraft-java-edition-1-19-4 - PrismarineJS minecraft-data — versioned Minecraft data project useful for further block-data expansion:
https://github.com/PrismarineJS/minecraft-data - Minecraft Wiki display entity documentation for additional command behavior and version notes:
https://minecraft.wiki/w/Display