sprite2world

World Management with preview
Sprite editor
AI Sprite generator
Material generation
Generated ladybug as material
Overworld AI generation

The AI designs. Sprite2World engineers.

Sprite2World is a containerized, AI-assisted level-design tool that turns a collection of pixel-art sprites and a natural-language idea into a deterministic, validated, playable 2D world. Users can import PNG files or ZIP archives, classify assets, describe the world they want, generate a semantic blueprint with OpenAI, and immediately inspect and playtest the resulting map in the browser.

Inspiration

The project started with a recurring problem in 2D game development: having a folder full of promising sprites is not the same as having a playable level. Turning those assets into a coherent world still requires categorization, layout planning, collision rules, connectivity checks, iteration, and a great deal of manual placement.

Generative AI is good at interpreting creative intent, but asking a model to output thousands of exact tile coordinates is fragile and difficult to reproduce. We wanted a clearer division of responsibility: let AI understand the visual assets and propose the structure of a world, while conventional software engineering remains responsible for coordinates, rules, validation, and playability.

That idea became the central principle of Sprite2World:

AI expresses intent; deterministic code builds the world.

What it does

Sprite2World provides an end-to-end workflow for creating a playable top-down level:

Import pre-sliced PNG sprites, multiple files, folders, or ZIP archives.
Review the adaptive sprite library and assign semantic roles manually or with OpenAI vision classification.
Describe the desired world in natural language.
Generate a schema-constrained semantic blueprint containing regions, connections, themes, and gameplay intent.
Convert that blueprint into rooms, corridors, walls, objects, collision cells, a player start, and an exit.
Validate reachability, connectivity, overlaps, boundaries, collisions, and asset references.
Repair bounded obstacle problems automatically and display remaining diagnostics.
Playtest the result immediately with keyboard controls.
Improve the world through natural-language feedback, restore earlier versions, or export the full project as JSON and a PNG preview.

The editor also includes a deterministic offline demo workflow. This means the core product remains explorable even when no OpenAI API key is configured or an AI request is unavailable.

How we built it

Sprite2World is completly built with Codex (ChatGPT 5.6 Sol) C# and .NET 10 as a Blazor Web App. Docker Compose starts two services:

sprite2world-web provides the browser editor, project state, OpenAI orchestration, and Canvas integration.
sprite2world-worker performs bounded file processing, deterministic world generation, validation, repair, and preview rendering.

Only the web service is exposed to the host. The worker stays on an internal Docker network, and both services share a named volume for JSON project files and imported assets. This keeps installation simple: users only need Docker and a browser—no local .NET SDK, Node.js installation, database, or message broker.

The OpenAI Responses API is used for asset classification, blueprint creation, and feedback-driven revision. AI responses use strict Structured Outputs and are deserialized into an OpenAI-independent semantic model. The model never supplies final tile coordinates.

The concrete map is produced by a seeded TopDownRooms generator. Conceptually, the result is a pure function of the validated inputs:

$$ W = f(B, A, S, V) $$

where $W$ is the generated world, $B$ is the semantic blueprint, $A$ is the classified asset manifest, $S$ is the seed, and $V$ is the generator version. Keeping these inputs constant produces the same world again.

An independent validator then checks the generated result using grid traversal and flood-fill logic. It verifies that the exit is reachable, required regions are connected, rooms do not overlap incorrectly, collision data is valid, and every referenced asset exists. A bounded repair step can remove blocking obstacles without silently redesigning the level.

The browser renders the world through a lightweight JavaScript Canvas layer with pan, zoom, grid, minimap, camera following, and keyboard playtesting. Project data is stored as JSON, while a dependency-free PNG encoder creates diagnostic previews.

Challenges we faced

Creating a reliable boundary between AI and game logic

The hardest design decision was deciding what the model should control. Giving AI complete control over tile placement would have made results inconsistent and difficult to validate. We instead designed a compact semantic blueprint schema and moved all spatial engineering into deterministic C# code.

Making generated worlds genuinely playable

A visually plausible map can still contain an unreachable exit, disconnected regions, invalid collisions, or blocked corridors. We built validation as an independent stage rather than trusting the generator. This separation made failures explainable and allowed safe, bounded repairs.

Handling arbitrary user assets safely

File import introduced its own security and reliability problems. The importer validates extensions, sizes, PNG signatures, dimensions, normalized paths, duplicate entries, and extraction limits. ZIP entries are checked against path traversal before anything is written.

Preserving determinism while supporting iteration

Creative feedback should change the design without turning the system into an unpredictable black box. We therefore version semantic blueprints and preserve seeds and generator metadata, allowing users to understand what changed and restore earlier results.

Delivering a zero-setup experience

The project spans browser UI, server-side AI calls, file persistence, and CPU-oriented generation. Packaging everything into two healthy Docker services—while correctly publishing Blazor's interactive browser assets—was an important final challenge. The result can now be cloned and started with a single Docker Compose command.

What we learned

We learned that AI becomes more useful when its responsibilities are deliberately constrained. Strict schemas do not reduce creativity; they create a dependable contract between creative intent and deterministic systems.

We also learned that generation and validation should be separate concerns. A generator tries to produce a good result, while a validator assumes nothing and proves whether the result satisfies the rules. That distinction is especially valuable for AI-assisted workflows.

Finally, we learned how important graceful degradation is. By including deterministic demo content and an offline fallback, Sprite2World remains testable even without external services. This made the product easier to demonstrate, debug, and trust.

What we are proud of

Sprite2World does more than create a visually interesting image. It produces a structured world with rooms, connections, collisions, a start position, an exit, validation results, version history, and exportable data. Users can immediately play what they generated and inspect the reasoning boundary between AI design and deterministic engineering.

What's next

The current release intentionally focuses on one reliable grammar: TopDownRooms. Future versions could add overworld, city, platformer, and multi-floor generators; sprite-sheet slicing and animation; richer editing tools; collaborative projects; and exporters for engines such as Godot, Unity, and Tiled.

The long-term goal is to make Sprite2World a transparent bridge between creative assets, natural-language direction, and production-ready level data.