UX and engineering lessons from turning a world viewer into a task-finding tool
A map viewer can render every tile correctly and still fail the player.
The reason is simple: most players do not open a world map because they want to admire a complete data visualization. They open it because they have a question.
Where is the Dungeon? Which chest contains the item I need? Did this world generate a particular structure? What is at these coordinates? How do I get from the result on screen to the same place in the game?
Rendering answers “what does the world look like?” Search has to answer “where is the thing I care about?”
While improving TerraMap, a browser-based Terraria world viewer, I found that the hardest product decisions were not about drawing more pixels. They were about translating a large, structured game world into a small set of player tasks.
Here are the design and engineering patterns that made the difference.
Start with questions, not data categories
Game data naturally arrives in technical categories: tiles, walls, liquids, chests, items, NPCs, world properties, and entities. These categories are useful to the parser, but they are not always how players formulate a goal.
A player may ask for “the Dungeon,” which is partly a world property and partly a recognizable structure. They may ask for “Shimmer,” which is a liquid inside a mini-biome. They may ask for an accessory, but what they actually need is the chest containing it. They may have coordinates from a friend and want to go directly there without searching by name at all.
The interface should therefore expose task-shaped entrances:
- Quick navigation for spawn, the Dungeon, and exact coordinates.
- Common finds for frequent structures, resources, and environmental targets.
- Search by name for players who know the object they want.
- Result navigation for moving through multiple matches in the current world.
Technical categories still matter, especially when two objects share a name. But they should clarify a task rather than define the entire interface.
Make the file-to-answer path explicit
For a local world viewer, the player journey begins before the map exists.
The complete path is:
choose world → parse → render → find → navigate → inspect
Each transition can fail independently.
The player may choose the wrong file type. Parsing may encounter an unsupported version. The map may load, but search indexes may not be ready. Search may return hundreds of matches without a way to navigate them. The correct coordinate may be highlighted, but the player may not understand the surrounding terrain well enough to reproduce the route in-game.
Thinking in this sequence prevents a common mistake: optimizing the central map canvas while leaving the steps around it ambiguous.
A useful interface answers these questions at the moment they arise:
- Which file do I need?
- Is the file still being processed?
- Did the world load successfully?
- What can I search?
- How many matches exist in this world?
- Which match am I viewing?
- What is around it?
- How do I reach another result?
If the map is fast but the player cannot answer those questions, the product still feels slow.
Separate quick actions from exhaustive search
Not every task needs a search field.
Spawn and Dungeon positions are known world properties. An exact coordinate is already an answer supplied by the player. Frequently requested structures can be offered as curated actions. Sending all of them through one universal search box creates unnecessary typing and forces players to learn the tool’s vocabulary.
This suggests a hierarchy:
- direct navigation for known positions;
- curated common searches for frequent goals;
- open-ended name search for the long tail;
- filters for resolving ambiguous categories.
The hierarchy also works well on mobile. A short list of high-value actions can remain accessible in a compact tools panel, while the exhaustive selector opens only when requested.
The danger is allowing “common finds” to grow into another unsearchable menu. Curate them based on recognizable player tasks, group them by meaning, and keep the full search available for everything else.
Search stable objects, display player language
The search index should be built on stable game identifiers and coordinates, not on the display string currently visible in the interface.
Names are presentation and query vocabulary. They can change by language or game version. Object identity determines which locations should be highlighted.
This separation supports a useful flow:
query text → localized name or alias → object identifier → indexed coordinates → camera movement and highlight
It also prevents language switching from changing the meaning of an already parsed world. The same tile remains the same tile whether its label is shown in English, Japanese, German, or Portuguese.
Aliases deserve special care. Placed objects and inventory items may represent the same player-recognizable concept while using different identifiers. Sharing relevant search vocabulary can help the player find the placed form using the item name they remember. But the result must retain its original type so that highlighting and counts remain accurate.
Search convenience should never blur the data model so far that the map highlights the wrong category.
Build indexes while the world is already being parsed
The world parser has to visit the data. That is the best time to prepare the most important search structures.
If the application waits until the first query to scan a large world, the player experiences the cost as search latency. If it rescans for every query, the cost repeats. Building compact indexes during parsing moves that work into a phase the player already expects and makes later interactions much faster.
Useful indexes can include:
- coordinates by tile type;
- coordinates by wall type;
- positions of relevant liquids;
- chest origins by contained item;
- world-property locations such as spawn and Dungeon;
- one origin for a multi-tile object instead of one result per occupied tile.
The last point matters more than it appears. A four-tile object should not usually produce four search results. A chest containing several stacks of the same item should not necessarily become several identical map positions. Results should represent navigable places, not raw storage entries.
Deduplication belongs close to index construction, where the application still understands why two records refer to the same location.
Result counts are part of navigation
“Found” is not a sufficient search state.
If a world contains 63 matches, the player needs to know that there are 63, which one they are viewing, and how to move through them. A simple 7 / 63 indicator changes the interaction from repeated searching into a predictable navigation loop.
The essential controls are:
- total number of results;
- current position within the result set;
- previous and next actions;
- a clear way to remove the highlight;
- a camera move that preserves enough surrounding context.
Wrapping from the last result to the first can be useful, but it should be consistent. Keyboard and pointer interactions should produce the same ordering. A new query should reset the current position deliberately rather than inheriting a stale index from the previous result set.
Counts also expose data bugs. If a player sees hundreds of duplicates for a single structure, the result summary makes the problem visible immediately.
Coordinates need two languages: data and game
Internal map coordinates are usually optimized for storage and rendering. Players may think in the coordinate system shown by an in-game item, including east/west distance, depth, and named layers.
Both forms can be useful, but they should not be conflated.
An exact coordinate input needs explicit X and Y fields, integer validation, and visible valid ranges derived from the loaded world. Invalid input should remain visible with a clear error; silently clamping it to the nearest valid value makes the tool appear to accept a coordinate it did not actually use.
The result display can then translate internal tile coordinates into player-facing location language. This helps the player connect a point on the viewer to what they will see in-game.
Coordinate conversion is a deceptively small area where off-by-one errors and swapped axes can destroy trust. It deserves fixture-based tests with known world positions, not only visual checking.
Preserve context when jumping
A search result is rarely useful as a single highlighted pixel.
The player needs enough surrounding terrain to recognize the route, nearby tunnels, biome boundaries, or structures. Jumping too close removes context; staying too far out makes a rare object impossible to see.
A good jump behavior selects a useful zoom level, centers or sensibly offsets the result, and adds a highlight that remains visible against different map colors. The player should still be able to pan, zoom, inspect tiles, and compare nearby landmarks.
For connected liquids or large structures, highlighting every relevant tile may communicate shape better than marking only one coordinate. For multi-tile furniture, one stable origin may be clearer. The visualization should follow the object’s meaning, not one universal marker rule.
Give players control over spoilers
A complete world map is powerful because it reveals everything. That is also its main risk.
Some players want a direct answer and do not mind seeing unexplored structures. Others want help navigating only the areas their character has already discovered.
If the game provides player exploration data, an optional player map can act as a spoiler boundary: parse the world for structure, but display only the tiles that the selected player has seen. The interface must explain the limitation clearly so players understand why a valid search result might remain hidden.
Even without that feature, the product should acknowledge the tradeoff before revealing a full map. A player guide can offer manual clues first and the exact viewer method second. The right answer is not always maximum information as quickly as possible.
Performance should be measured by task latency
Frame rate matters, but it is not the only performance metric players feel.
Task-oriented latency includes:
- time from file selection to the first usable map;
- time until search is ready;
- delay between choosing a target and seeing the highlight;
- responsiveness while a large world is parsing;
- memory pressure after repeated searches and map interactions.
Several architectural choices help:
- parse in a worker so the interface stays responsive;
- report meaningful progress phases;
- build high-value indexes during parsing;
- render only what the current viewport needs;
- avoid recreating large arrays during every search;
- deduplicate positions before they reach the interface;
- keep selection state separate from parsed world data.
Performance testing should use representative Small, Medium, and Large worlds. A tiny fixture can prove correctness while hiding the costs that shape the real user experience.
The reusable lesson: design around answers
The most important change was conceptual. A world viewer is not primarily a map with controls around it. It is an answer system whose evidence happens to be spatial.
That framing produces better priorities:
- common questions become direct actions;
- the long tail remains searchable;
- identifiers keep results correct across languages;
- indexes make repeated tasks fast;
- counts turn matches into navigation;
- context helps players reproduce the result in-game;
- spoiler controls respect different play styles.
These principles apply beyond Terraria. Save editors, level analyzers, replay viewers, modding tools, and procedural-world debuggers all sit between technical game data and a human question.
Rendering the data is necessary. Helping the user reach the right place—and understand why it is the right place—is the actual product.
