Civ4 XML Checker

[lfgr]

Civ4 XML Checker

Civ4 XML Checker (CXC) is an utility program that performs various tests to find possible XML errors in modifications for Sid Meier's Civilization 4.

Download

You can download CXC at the Download Section at Bitbucket. To install, simply extract the archive file anywhere.

The source and the bugtracker are found at the Project Home.

Installation and Running

To run the program, you need the Java 8 Runtime Environment installed. You can download it at http://java.com.

CXC is started via the command line with the command

java -jar cxc.jar [OPTIONS]

The following options are available:

• -conf <arg> - set the configuration file (see below, default: config.xml)
• -dir <arg> - set the XML base dir (default: ./XML)
• -help - display a help message and quit

On MS Windows and on linux with some file managers you can also just double-click cxc.jar or right-click and chose "Open with.../Java Runtime Environment" or similar if you don't need to supply options.

Compiling from source

CXC requires the following two libraries:

• jdom-2.0.6
• commons-cli-1.3.1

XML Checking

Note: below, "entity" refers to an XML datum in Civ, such as a CivilizationInfo, UnitInfo etc., but also the text tags in XML/Text.

The program performs various tests. If any test fails, it emits Errors and/or Warnings. Errors are designed to contain zero false positives, e.g. they should not be ignored.

Errors

• Any two entities have the same ID
• The same element in two entities refers to two entities of a different type (unless those types are declared as <equivalent-types> in the configuration file, see below). For example, in one file, the <Description> element of something refers two a unit, while other <Description> elements refer correctly to Text entities. NONE is always allowed
• An element starting with "i" doesn't contain an integer
• An element starting with "f" doesn't contain a float
• An element starting with "b" doesn't contain 0 or 1

Warnings

• The root element of a file is a designated ID element (such as <Type>)
• An entity root contains text

What CXC doesn't check

• References to missing entities: these should be catched by the engine
• Validity according to the XDR Schema: there are other utilities available to do this such as alberts2's Tool for XML Validation

Configuration

CXC is configured entirely in config.xml. It can guess the layout of most XML files with very little configuration, but for some there is more information required.

The basic configuration applies to Civilization 4: Beyond the Sword and should be sufficient for most mods.

config.xml has the following form:

<cxc-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="config.xsd">
    <id-elem name="..." />
    <id-elem name="..." parent="..." />
    ...

    <root-elem name="..." />
    ...

    <excluded-elem name="..." />
    ...

    <file name="...">
       ...
    </file>
    ...

    <equivalent-types>
       <type name="..." />
       ...
    </equivalent-types>
    ...

    <excluded-file pattern="..." />
    ...
</cxc-config>

<id-elem name="..." > specifies the name of an ID element to use for every file, such as Type. If the parent attribute is specified, additionally, the parent of the element must have the given name. An element containing an ID element automatically becomes the root element of a specific entity. An unlimited number of ID element names can be specified, though they shouldn't interfere with regular elements.

<root-elem name="..."> specifies the name of a root element. Typically needed if the entity doesn't have an ID element. An unlimited number of root element names can be specified, though they shouldn't interfere with regular elements.

<excluded-elem name="..."> specifies the name of an element not to check.

<file name="..."> specifies a file to treat in a special way. Can contain <id-elem>, <root-elem> and <excluded-elem> elements that only apply to the specified file.

<equivalent-types> specifies a set of types that are interchangeable when referenced. For example, several elements in Bts may contain either a Script2DSound or Script3DSound.

<excluded-file pattern="..." /> excludes all files matched by the specified pattern. For pattern syntax, see http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html.

Licenses

• GNU GPL v3 for CXC (LICENSE.txt)
• JDOM license (LICENSE_jdom.txt)
• Apache license 2.0 for commons-cli (LICENSE-commons-cli)