Crossfire Server, Trunk  1.75.0
Crossfire Mapper

Overview

Crossfire Mapper is an offline tool, not required to host a server or play the game.

This program generates web pages listing all maps, items, monsters, regions, and many more things. It can be customized to output almost any format.

Quick run: without arguments, will make sensible choices.

For help, try the -help option.

Since this program browses maps from the first map, only maps linked from there will be processed. A command line parameter, -addmap=, allows to specify more maps.

Maps are generated as the server sees them, that is with weather effects, treasures instead of markers, and things like that.

Generated files use "templates", stored (by default) in "templates/" subdirectory. A list of files to process is specified on the command line (by default "index.html"), and from there the program will generate all requested pages.

Templates use the inja C++ template engine, found at https://github.com/pantor/inja as well as Nlohmann JSON, at https://github.com/nlohmann/json

Provided templates should give much samples of use, see "index.html" for entry point.

Available objects in templates

In templates, the following objects are defined:

  • map: identified by a unique key, with the following fields:
    • _key: unique map key
    • name: map name as defined in the map itself
    • path: map path from the map root
    • region: key of the region this map is part of
    • level: map level as defined in the map
    • reset_group: reset group of the map, empty if not specified
    • lore: map lore as defined in the map
    • exits_to: array of map keys that this map contains exits to
    • exits_from: array of map keys that link to this map
    • npcs: array of npc objects that are on this map
    • readables: array of npc objects that represent books on this map
    • monsters: array of monster objects
    • quests: array of quest_in_map objects that this map is part of
  • region: identified by a unique key, the following fields are defined:
    • _key: unique region identifier
    • name: region short name
    • longname: region long name
    • description: region description
    • maps: array of map keys that are part of the region
    • links: array of region keys this region has exits to
  • item: contains the following fields:
    • name: item name as found on the map
    • power: item power as found on the map
    • calc_power: item power as computed by the game
    • diff: item specific fields, as an (CF) object difference with the archetype
    • maps: array of map keys the item is found on
  • monster: contains the following fields:
    • name: monster's name
    • count: how many are found in the world
    • maps: array of map keys the monster is found on
  • system_quest: information about a quest, with the following fields:
    • code: unique quest code
    • title: quest title as seen by the player
    • description: long description, as seen by the player
    • steps: only filled if the command-line parameter "-details-quests" is specified, array of steps:
      • description: step description
      • is_completion: true if this step completes the quest, false else
  • slaying: information about a key, detector and such, with the following fields:
    • slaying: unique code
    • doors: array of map keys that contain a door with this slaying
    • keys: array of map keys that contain a key with this slaying
    • containers: array of map keys that contain a container with this slaying
    • detectors: array of map keys that contain a detector with this slaying
    • connections: array of map keys that contain a connection with this slaying
  • quests: information about a quest as defined in map parameters, with the following fields:
    • _key: unique quest key
    • number: unique quest number
    • name: quest name, may be empty
    • description: quest description, may be empty
    • main_map: key of the main map of the quest, may be empty
    • maps: array of quest_in_map objects
  • quest_in_map: information about a link between a map and a quest
    • map: map key
    • description: relationship between the quest and the map
    • quest: quest name
    • number: unique quest number *
  • npc: information about a NPC or a readable (book, sign, message...), fields:
    • name: NPC or readable name as defined in the map
    • x: coordinate in the map
    • y: coordinate in the map
    • message: NPC or readable message
  • monster: information about a monster, fields:
    • name: monster name
    • count: number on the map

The following variables are available to the templates:

  • maps: list of maps
  • regions: list of regions
  • items: list of special equipment
  • monsters: list of monster objects
  • system_quests: list of system quest objects
  • slaying: list of slaying information objects
  • quests: list of quests defined in map objects
  • has_search: only true if mapper should generate browser-side search data.

As well as default callbacks provided by inja, mapper adds the following ones:

  • link_to_page(page_name[, param]): process the "page_name" template, and return a link to the file. "param" is an optional string that the template will be able to access via the "param" variable. Pages with the same "page_name" and "param" are considered equal.
  • substr(what, start[, length]): return the substring from "start", of a specified length or the end of the string.
  • picture(item_key[, size]): return the path to the picture of the specified item. "size" is 1 (default) to 5, with 1 real size and 5 the smallest size. Only map keys are allowed for now.
  • pad(val, digits): pad "val" to a string of "length" characters, adding 0 in front if needed.
  • path_to_root: return the relative path, without final /, to the output root of generated files.
  • sort(list, keys[, invert[, ignore_case]]): sort the specified list by the value of 'keys', which may include multiple field names separated by a comma. If 'invert' is true then invert order. Strings are compared in a case-unsensitive manner unless 'ignore_case' is false.
  • get_by_field(list, field, value): return the first item in the list having a field 'field' with value 'value'.
  • get_list_by_field(list, field, value): return all items in the list having a field 'field' with a value in the list 'value' (if value a list) or the value 'value' (if value a single value).

For maps, 5 pictures are generated, with sizes of 32, 16, 8, 4 and 2 pixels for tiles.

Building

This program was only tested under Linux.

To build this program, add the –enable-mapper flag to configure then run make at the server root. Compilation requires the GD library and its development files.

Browser-side search

With the HTML output, mapper can generate browser-side search facilities, using LunaJS.

The easiest was to generate the search index is to use the provided mapper-with-search.sh script, which uses Docker to run the required JS parts.

When mapper is run with the -build-search-data option, has_search is defined to true in the templates.

The search index uses files from "templates/search-links" to generate links for results, depending on the type.