- This is a development draft that is a work in progress

This FAQ covers the Gridarta map editor as used with the Crossfire RPG. It addresses installation, configuration, common usage questions, troubleshooting, and contributing maps. For general Crossfire gameplay questions, refer to the main Crossfire FAQ.

Gridarta is a free and open source (GPLv2) Java-based map editor for 2D MMORPGs. It is the official and actively developed map editor for the Crossfire RPG project. In the Crossfire context, Gridarta is also referred to as CrossfireEditor or Gridarta4Crossfire.

Gridarta also supports the Daimonin and Angelion game projects, but its Crossfire support is the most fully developed and actively maintained variant.

The project is hosted on SourceForge: https://sourceforge.net/projects/gridarta/

Gridarta succeeded two earlier Crossfire map editors, both of which are now discontinued:

• CF Edit (Crossedit) — The original X11-based map editor, removed from the server source tree in 2007.
• CF Java Editor — The first Java-based editor, which Gridarta replaced.

Gridarta provides a graphical interface for creating and editing Crossfire maps. Its main features include:

• Creating new maps of a specified size and configuring map-level properties.
• Editing existing maps by placing, moving, and deleting game objects (archetypes) on a tile grid.
• Browsing and selecting archetypes from a categorized pickmap panel.
• Editing individual game object attributes in a dedicated attributes editor.
• Searching for archetypes by name using the Find Archetypes dialog.
• Map validation, which checks for common errors such as invalid exits, duplicate monsters on a tile, and malformed NPC dialog messages.
• Exporting a map as a PNG image (via Tools → Export Map As Image…).
• Zooming the map view in and out (via Tools → Zoom).
• Scripting support using an embedded editor or an external editor of your choice.
• Going to a specific map by path using the Goto Map dialog.

Yes. Gridarta is the currently supported and developed map editor for Crossfire. Commits continue to be made to the repository, including archetype updates and bug fixes. The project activity page on SourceForge shows recent commits.

Gridarta runs on any operating system (Windows, Unix, Linux, and macOS). To use it, you need to install a Java Runtime Environment (JRE) v1.6.0 or newer. However, Java 8 (JRE 1.8) is the recommended version for building Gridarta, and the Windows all-in-one installer bundles a suitable JRE automatically.

In addition to the editor itself, you will need the Crossfire map files to edit. These should be obtained via Git (see Section 2.5).

There are two download options depending on your platform:

A platform-independent JAR file is available from the official Crossfire project page:

• https://sourceforge.net/projects/crossfire/files/gridarta-crossfire/

To launch the JAR file, double-click it (requires a working Java installation) or run:

java -jar CrossfireEditor.jar

A Windows installer that bundles both Gridarta and a Java Runtime Environment is available. This is the recommended option for Windows users as it requires no separate Java installation:

• Latest stable installer: https://sourceforge.net/projects/crossfire/files/gridarta-crossfire/
• Automated daily build (may contain experimental features): http://crossfire.weeger.org/GridartaForCrossfireInstaller-latest.exe

The installer README is available at: https://sourceforge.net/projects/crossfire/files/gridarta-crossfire/README-gridartainstaller.md/download

Using the all-in-one installer (recommended):

1. Download the Windows installer .exe file from the download link in Section 2.2.
2. Run the installer and follow the on-screen prompts.
3. Launch the editor from the Start menu or the desktop shortcut.

Using the JAR file:

1. Download the CrossfireEditor.jar file.
2. Ensure a compatible Java Runtime Environment (Java 8 or later) is installed on your system.
3. Double-click the JAR file to launch the editor.
4. You may wish to move the JAR file to a convenient location such as your Desktop first.

When Gridarta first launches, you will likely see warnings about missing autojoin files, a missing script directory, and an invalid pickmaps directory. This is expected if you have not yet pointed Gridarta at a local copy of the Crossfire maps. Click OK to dismiss these messages and proceed.

1. Install a Java Runtime Environment (JRE or JDK) version 8 or later using your distribution's package manager. For example:
   • Debian/Ubuntu: sudo apt install default-jre
   • Fedora: sudo dnf install java-1.8.0-openjdk
2. Download the CrossfireEditor.jar file from the Crossfire download page.
3. Launch the editor:

java -jar CrossfireEditor.jar

Installation guides for specific Linux distributions (Ubuntu, Debian, Fedora, Linux Mint) are available on the Crossfire website under Editors → Java Installation.

macOS typically includes a Java Runtime Environment, or one can be installed from the official Java website. Once Java is available, download the CrossfireEditor.jar file and double-click it to launch. A dedicated guide is available at https://crossfire.real-time.com/editors/install/macosx-v6-jre.html.

Gridarta requires a local copy of the Crossfire map files in order to be useful. Maps are obtained by cloning the repository from SourceForge using Git:

git clone https://git.code.sf.net/p/crossfire/crossfire-maps crossfire-maps

You will also need the archetype files, which define all the game objects available to place on maps:

git clone https://git.code.sf.net/p/crossfire/crossfire-arch arch

After cloning, configure Gridarta to point at these directories via File → Options (or File → Preferences depending on your version).

For a complete development environment that allows you to test maps on a local server, you should also clone and compile the server itself. See the Crossfire Wiki Development page for a step-by-step guide.

- Update to use Docker

Building Gridarta from source requires:

• Java Development Kit (JDK) version 8 or higher (openjdk-8-jdk or Sun JRE 8).
• Gradle (version 4.4.1 or higher is known to work).

To build:

git clone https://git.code.sf.net/p/gridarta/gridarta gridarta
cd gridarta
gradle build

The resulting JAR file will be produced in the build output directory. Full build documentation is available in the Gradle documentation for Gridarta.

When Gridarta first starts without a configured environment, it will warn about missing paths. Open File → Options (or the equivalent preferences dialog) and set the following directories:

• Maps directory — the root of your cloned crossfire-maps repository.
• Archetypes directory — the root of your cloned crossfire-arch repository, which contains the archetype definitions and images.
• Pickmaps directory — usually the resource/pickmaps/ folder within the Gridarta or archetypes directory. This controls the archetype palette shown in the editor.
• Script directory — the directory used for Crossfire Python scripts (relevant if your maps use scripts).

After setting these paths, restart Gridarta for the changes to take effect.

The –use-mapdir option changes how Gridarta interprets map file paths passed on the command line. Without this option, map file paths are treated as absolute or relative filesystem paths. With –use-mapdir, the paths are interpreted as relative paths within the configured maps directory. This is useful when opening a specific map from a script or shortcut.

Example:

java -jar CrossfireEditor.jar --use-mapdir scorn/scorn

By default, Gridarta uses a built-in text editor for editing Crossfire Python scripts. To use an external editor instead, go to File → Options and under External Applications → Editor, enter the command for your preferred editor.

Examples:

• emacs
• xterm -e vim
• “C:\Program Files\Notepad++\notepad++.exe”

Spaces in the command name or arguments can be quoted. The file to be edited is automatically appended as the last argument when the external editor is launched.

Pickmaps are the panels on the side of the Gridarta interface that contain categorized collections of archetypes available for placement on maps. They function as a palette or toolbox. Each pickmap typically represents a category such as walls, floors, monsters, items, NPCs, doors, or special objects.

When you select an archetype from a pickmap and then click on the map canvas, that archetype is placed on the map tile you clicked.

In Crossfire, an archetype (often abbreviated as “arch”) is the template definition of a game object. Archetypes define everything about an object: its name, graphic, attributes, behavior, and type. Examples include walls, floor tiles, monsters, weapons, doors, signs, NPCs, and teleporters. Every object placed on a map is an instance of an archetype, and can have its attributes customized relative to the base archetype definition.

Gridarta loads archetype definitions from your local archetype repository and uses them to populate the pickmap panels and the archetype attribute editor.

1. Go to File → New Map (or use the New Map toolbar button).
2. In the dialog that appears, specify the map's name, width, height, and other initial properties.
3. Click OK to create the empty map.
4. Begin placing archetypes by selecting them from the pickmap panels and left-clicking on the map canvas.
5. Save the map with File → Save or Ctrl+S.

Go to File → Open and navigate to the map file you wish to edit. Crossfire map files have no special extension — they are plain text files typically stored within the crossfire-maps directory hierarchy.

Alternatively, you can use the Goto Map dialog to open a map by its path relative to the configured maps directory.

1. Select an archetype from the pickmap panel on the side of the editor.
2. Left-click on a map tile to place the selected archetype on that tile.
3. To remove (delete) an object, right-click on it on the map canvas.
4. Each map tile can hold a stack of multiple objects (for example, a floor tile at the bottom with a wall or item on top).

1. Click on the object in the map canvas to select it.
2. The Game Object Attributes Editor panel will display the object's editable attributes.
3. Modify the values as needed. Tooltips are shown for each attribute field to explain its purpose.

This editor allows you to customize virtually any attribute of a placed object relative to its base archetype — for example, changing a monster's name, hit points, or experience value, or setting the destination of an exit.

Go to Edit → Map Properties (or the equivalent menu entry) to open the map properties dialog. Here you can set properties such as:

• Map name and description (shown to players when they enter the map).
• Map dimensions (width and height in tiles).
• Difficulty level (influences what treasure generators produce).
• Reset time (how long before the map resets and monsters respawn after all players leave).
• Fixed reset time (resets the map at a fixed interval regardless of player presence).
• Darkness level (0 = full daylight, higher values = darker).
• Outdoor flag (marks the map as an outdoor map, affecting certain game mechanics).
• Tile path connections (links this map to adjacent maps for seamless world travel).
• Map lore (background text visible through the mapinfo command).

Crossfire maps can be connected to adjacent maps so that walking off one edge of a map moves the player seamlessly to the neighboring map. This is how the open world is constructed.

In the map properties dialog, tile path fields (typically labeled Tile 1 through Tile 4, corresponding to North, East, South, and West, or similar) allow you to specify the relative path to the adjacent map file. Both the current map and the target map must have matching tile connections set for seamless travel to work correctly.

Exits and teleporters are game objects that move a player to a different location when applied or stepped on.

To configure an exit:

1. Place an exit archetype on the map from the pickmap panel.
2. Select the placed exit and open the Game Object Attributes Editor.
3. Set the slaying (or hp and sp) attributes to the target map path and coordinates:
   • slaying — the path to the destination map file, relative to the maps directory.
   • hp — the X coordinate of the arrival point on the destination map.
   • sp — the Y coordinate of the arrival point on the destination map.

Gridarta's built-in validators include an Invalid Exit check that will warn you if the destination map path or coordinates are invalid.

Use Edit → Find Archetypes (or the equivalent toolbar button) to open the Find Archetypes dialog. Type a partial or full name of the archetype you are looking for and the dialog will filter the list of matching archetypes. You can then select one and place it on your map.

Go to Tools → Export Map As Image… to render the current map to a PNG file. This is useful for documentation, sharing previews, or comparing map layouts.

Use Tools → Zoom to change the zoom level of the map view. This menu entry is only enabled when a map is open.

Yes. Crossfire uses Python scripts for NPC behavior and dialogs. Gridarta can open these scripts in either its built-in text editor or in an external editor of your choice (see Section 3.3). Select the scripted game object on the map, then use the script editing option in the attributes editor or the relevant menu entry.

Gridarta includes a map validation system that automatically checks open maps for common errors and reports them in an Error View panel. Validation runs as you work, or can be triggered manually.

Validation errors and warnings highlight problems that could cause issues in the game, such as broken exits, improperly configured objects, or formatting errors in NPC dialog text.

Gridarta for Crossfire includes several map validators. Known validators include:

• Invalid Exit — Warns if an exit's destination map path does not resolve to a valid file, or if the destination coordinates are out of bounds.
• Duplicate Monster — Warns about map squares that contain more than one monster archetype stacked on the same tile, which is typically a map design error.
• Suspicious msg value — Warns about malformed msg…endmsg blocks in NPC dialog objects. This validator helps catch syntax errors in dialog text that would cause problems in the game engine.

Validators can be individually enabled or disabled in the preferences dialog.

Validation errors appear in the Error View panel. Clicking on an error in this panel will jump the map view to the problematic tile, making it easy to locate and fix the issue.

These warnings are normal when Gridarta has not been fully configured to point at your local Crossfire map and archetype repositories. You can safely click OK to dismiss them.

To resolve the warnings permanently:

1. Clone the Crossfire map and archetype repositories (see Section 2.6).
2. Open File → Options and configure the maps directory, archetypes directory, and pickmaps directory to point at the correct local paths.
3. Restart Gridarta.

Gridarta handles this gracefully. When a map file contains game objects located outside the defined map boundaries (usually a sign of a corrupted or incorrectly edited map file), Gridarta displays a warning dialog and then loads the map while ignoring the out-of-bounds objects. The map can then be saved, which will discard the invalid objects and correct the file.

This was a regression that was introduced and subsequently fixed in the codebase. Make sure you are using a reasonably current build of Gridarta. Download the latest JAR or Windows installer from the Crossfire download page (see Section 2.2).

Ensure that a compatible Java Runtime Environment is installed and that .jar files are associated with Java. Try launching from a terminal instead:

java -jar CrossfireEditor.jar

If you receive a java: command not found error, install the JRE using your package manager (see Section 2.4).

In older versions of Gridarta, reducing the map size while the map cursor was positioned within the area being clipped off could cause a crash. This has been fixed. If you are encountering this issue, update to a current build of the editor.

The full ChangeLog for Gridarta is available on SourceForge:

• https://sourceforge.net/p/gridarta/gridarta/ci/master/tree/ChangeLog
• A full GitLog is also available at: http://crossfire.real-time.com/git/gridarta/gitlog/index.html

Yes. The Crossfire project has detailed map design guidelines that all contributed maps are expected to follow. These are essential reading before creating maps intended for submission to the official distribution:

• Map Making Guide — What is acceptable and what to avoid
• General Suggestions for map design
• Features to avoid in maps
• How to configure shops on maps
• Technical suggestions
• Crossfire Wiki — Dev section — Includes links to map making notes and the scale/size “Yardstick” guide.

The map difficulty setting in the map properties dialog influences the power level of treasure and monsters generated on the map. As a rough guideline:

• Difficulty 1–5 — Suitable for beginner and starting areas.
• Difficulty 6–15 — Intermediate content.
• Difficulty 16-50 — Advanced content.
• Difficulty 51+ - Endgame content

The difficulty should roughly match the level of monsters you are placing manually. Refer to the Map Guide and the Crossfire Map Atlas for examples of how existing maps set their difficulty relative to their monster population.

When all players leave a map, it will eventually reset — all monsters respawn and the map returns to its original state. The reset time is set in the map properties. The fixed reset time option forces the map to reset on a fixed schedule, regardless of whether players have been present.

Avoid placing objects or designing puzzles that rely on persistent state unless you specifically configure maps to prevent resets (which is generally discouraged except for special-purpose maps).

The Duplicate Monster validator warns when more than one monster archetype is stacked on the same map square. In practice, this typically results in one monster being directly on top of another at the start, which is a map design mistake. Each monster should occupy its own square, or monster generators should be used to control spawn density.

Shops require specific floor archetypes (shop floor tiles) and have several configurable parameters including the shop name, what item types it buys and sells, and pricing multipliers. Refer to the Shops guide on the official website for detailed instructions on setting up shops correctly.

1. Create and thoroughly test your map using Gridarta and a local Crossfire server.
2. Ensure your map complies with the Map Making Guide.
3. Announce your completed map on the Crossfire Maps mailing list.
4. Depending on the size of your submission, you may send a Git patch or diff directly to the list, or arrange for the files to be reviewed and merged via the SourceForge patch tracker.

The preferred workflow for regular contributors is to work with a local Git clone of the maps repository, commit changes locally, then submit patches for review.

git clone https://git.code.sf.net/p/crossfire/crossfire-maps crossfire-maps

After making changes, generate a patch for review:

git diff > my-map-changes.patch

Or, if you have commit access, push your changes directly to the repository.

• Bug reports and feature requests for Gridarta can be filed on the SourceForge project page.
• Patches can be submitted through the SourceForge tracker or discussed on the Crossfire Discord or IRC channel.
• When submitting a patch, keep it focused on a single change. State clearly what the patch fixes or adds, and which version of Gridarta it applies to. Avoid combining unrelated changes in a single patch.

The Gridarta source code is hosted on SourceForge using Git:

git clone https://git.code.sf.net/p/gridarta/gridarta gridarta

The main project page is: https://sourceforge.net/projects/gridarta/

Javadoc API documentation for Gridarta is generated from the source and published on the Crossfire website:

• Doxygen documentation for Gridarta
• Javadoc index

• Gradle documentation for Gridarta

• Crossfire Resource Editor (CRE) — A GUI tool for editing quests, objects (archetypes), and monsters without editing raw text files. Useful alongside Gridarta for object and quest design.
• cfdb_convert — A command-line utility for converting server databases, needed when upgrading a server from Python 2 to Python 3 (relevant since the Crossfire 1.75.0 release).
• crossfire-collect-archetypes script — A shell script used to collect archetype data for building the image and archetype archive files used by the server.

• Crossfire Map Editor Index — Official editor overview page.
• Gridarta page on the Crossfire website
• Crossfire Download Page — Download Gridarta and all related files.
• Crossfire Wiki — Development — Development guides, map making notes, and contributing information.
• Gridarta ChangeLog on SourceForge
• Crossfire Map Guide — Essential reading for map makers.
• Windows 10 Installation Guide — Step-by-step guide for installing Gridarta on Windows.
• macOS Installation Guide
• Crossfire IRC Channel — #crossfire on irc.libera.chat
• Crossfire Discord Channel
• Crossfire Maps Mailing List — For map-related discussion and submissions.
• Crossfire Web Forum