The commander’s guide

Custom maps and mods

Play maps you make yourself, share them with friends automatically when you host, and change the match rules: the .petalmap format, every field, its checks and a complete example.

Since Petalwar 0.5.29 you can play maps you make yourself and maps other players give you. When you host a match on one, the game sends the map to everyone who joins. A map can also change a few of the game’s rules: how fast things are built, how much you earn, what units cost and what you start with. It is the first step towards mods.

A custom map is one small text file whose name ends in .petalmap. It holds no level and no art, only a description: where the bases stand, where the river runs, where the lakes, mesas, islands and stone bridges are, where the extra crystal deposits lie and where the roads go. When the match starts, the game builds the ground, forests, rocks and bridges from it by the same rules as its own maps. A built-in map exported to a file plays exactly like the original.

Play a custom map

1. Open Skirmish, or Multiplayer and then Host game.
2. Scroll past the built-in maps to the Custom maps heading.
3. Pick a map and start as usual.

Two example maps come with the game: Foxtail Fork, written by hand, which also changes all five rules, and Sedgewater Narrows, the built-in map exported to a file.

Your own maps go in your maps folder. Open folder under the Custom maps heading opens it. Put .petalmap files there and press Rescan. The game creates the folder the first time you open that page.

A map with a mistake in it gets a red card that says what is wrong and where (see Checks and limits). Some things work differently on a custom map:

• Not rated. The match does not count for the highscores, because nobody can check whether a home-made map is fair or what its rules change.
• No achievements and no replay, because a replay would need the map file to play.
• A paused match is not kept when you leave it. The pause menu says so.

Play one with friends

You do not have to send the file to anyone. When a friend joins your lobby, their game asks yours for the map, and yours sends it over the match’s own connection. That works on your home network and through petalwar.com when you play by match code. Their game checks that it received exactly your file, then builds the ground. Sending a map takes about a second.

• The lobby shows “Receiving the map from the host…” to your friend and “Sending the map to …” to you. Nobody can ready up, and you cannot launch, until everyone in the lobby has the map, spectators included.
• The lobby says Custom map · unrated and lists the rules the map changes.
• Your friend’s game keeps each map it receives in Saved/Maps/Received, so a rematch or a rejoin sends nothing. Received maps stay out of their Custom maps list until they copy one into their maps folder.
• A map is known by its contents, the SHA-256 fingerprint of the file. Change one character and it is a different map, which your guests are sent again.
• The lobby’s Change map offers only the built-in maps for now, so pick the custom map before you host.

Make your own map

The easiest way is to copy an example and change it:

1. Open your maps folder with Open folder.
2. Copy FoxtailFork.petalmap into it from the game’s examples. On a Mac they are in Petalwar.app/Contents/UE/Petalwar/Content/CustomMaps (right-click the app, then Show Package Contents), and on Windows in Petalwar\Content\CustomMaps next to the game.
3. Rename your copy, open it in any plain-text editor (TextEdit in plain-text mode, Notepad, VS Code) and change its "title".
4. Edit it, save it, and press Rescan in the game.
5. Click its card. The game tests the map at once, and the card turns red if it does not play.

A map file is strict JSON. Put text in "double quotes" and separate items with commas, with no comma after the last one. Comments are not allowed, decimals take a dot (1.5, never 1,5), and the file must be saved as UTF-8.

The layout. Every map is a square 8 km across. Distances are in metres, and positions are [x, y] pairs: x runs from west (−4000) to east (+4000), y from south (−4000) to north (+4000), and [0, 0] is the middle. The ground rises into cliffs near the edges, so nothing stands past 3450 m east or west or past 3675 m north or south. A seat’s facing is measured from north, counter-clockwise (0 north, 90 west, 180 south, 270 east). A mesa’s ramp is measured from east, counter-clockwise, and snaps to the eight compass directions.

What every map gets anyway. At every seat the game places the Heartbloom and its five petals, the starting buildings and army, six crystal deposits and a small road network, all turned with the seat’s facing. Around every base it levels a 360 m home meadow. It also adds forests (kept off roads, deposits, ramps, water and meadows), shore rocks, flowers, waystones and supply caches. The water level is −8 m.

Every field

Only petalmap, title and seats are required. Any field the game does not know is an error, so a misspelled name is caught instead of quietly ignored.

A value out of range is refused with the range it must be in, so the error message tells you the limits as you go.

Change the rules (mods)

Add a rules object to make the match play differently. Every multiplier goes from 0.25 to 4, and 1 changes nothing. The rules are the same for every player and for the built-in AI.

The map’s card and the lobby show what its rules change. To play a built-in map with other rules, start from its exported file (Sedgewater Narrows comes with the game) and add a rules block. More rules, such as unit health, damage, speed and range and structure costs, are planned.

Checks and limits

When the game scans your maps folder it reads each file and reports the first mistake with its line and column, for example a comma before } (trailing commas are not allowed) (line 12, column 3), or seats[0].bsae is not a field of seats[0] (spelling? the fields are: base, facing, deposits, roads).

When you click a card, the game plays its rules on the map, which takes about half a second. Every bridge must reach dry ground at both ends, every home meadow must be dry, open and level, and every extra deposit must stand on dry, fairly flat ground an engineer can reach. Every base must be reachable from every other, over land or water. A card that fails says “Does not play:” and why. The game remembers each file’s result, so an unchanged file is not tested twice.

A guest only reads the map a host sends. A broken or deliberately harmful file is refused with a message, and it cannot crash their game.

A complete example

The smallest map that plays is two bases on an open meadow:

{
  "petalmap": 1,
  "title": "Open Meadow",
  "seats": [{"base": [0, -2500]}, {"base": [0, 2500], "facing": 180}]
}

Foxtail Fork, the hand-written example, has two bases facing each other across a river running east-west, two bridges, a mesa on each flank, three extra deposit pairs a side and a quicker game:

{
  "petalmap": 1,
  "title": "Foxtail Fork",
  "author": "Petalwar",
  "scenery": "pine",
  "mirroredNoise": true,
  "seats": [
    {"base": [0, -2600], "facing": 0,
     "deposits": [[-1500, -1700], [-1424, -1700], [1500, -1700], [1424, -1700], [0, -1250], [-2600, -2300]],
     "roads": [[[0, -2600], [0, -1900], [-900, -1000], [-900, 0]],
               [[0, -2600], [0, -1900], [900, -1000], [900, 0]],
               [[0, -2600], [-1500, -2350], [-2600, -2300]]]},
    {"base": [0, 2600], "facing": 180,
     "deposits": [[1500, 1700], [1424, 1700], [-1500, 1700], [-1424, 1700], [0, 1250], [2600, 2300]],
     "roads": [[[0, 2600], [0, 1900], [900, 1000], [900, 0]],
               [[0, 2600], [0, 1900], [-900, 1000], [-900, 0]],
               [[0, 2600], [1500, 2350], [2600, 2300]]]}
  ],
  "river": {"axis": "east-west", "amp1": 200, "period1": 900, "amp2": 30, "period2": 300,
            "width": 70, "widthAmp": 90, "widthPeriod": 900,
            "crossings": [-900, 900], "bridgeLengthScale": 1.25},
  "outcrops": [
    {"center": [-2500, -900], "rx": 420, "ry": 300, "height": 52, "ramp": 90},
    {"center": [2500, 900], "rx": 420, "ry": 300, "height": 52, "ramp": 270}
  ],
  "rules": {"buildTempo": 1.5, "economyTempo": 1.25, "unitCost": 0.8,
            "startingMatter": 1.5, "startingEnergy": 1.5}
}

Its crossings at −900 and 900 sit on its period1 of 900, period2 of 300 and widthPeriod of 900, so both bridges stand where the river crosses the middle line at its narrowest. The second seat is the first turned half round: every point negated and its facing 180 more. Together with "mirroredNoise": true, that makes the two halves identical. For three or four players, turn each seat’s whole pattern about the middle by 120° or 90°.

Tips. Change one thing at a time, then Rescan and click the card. Give the players something to fight over: deposit pairs halfway between the bases, a mesa by the middle bridge, a lake a fleet can hold. The minimap is drawn from your file, with water, rock, roads and woods, so it shows the layout at a glance.

Not there yet: switching a lobby to a custom map with Change map, replays and kept paused matches on custom maps, more rules, a map editor and random maps in the game, sharing maps on petalwar.com, and custom maps on iPhone and iPad.

All guide topicsBuilding field guideUnit field guide

Supreme Commander and Forged Alliance are trademarks of their respective owners. Petalwar is an independent game and is not affiliated with or endorsed by their makers or the Forged Alliance Forever project.