Custom Campaign XML

From BallisticNG Wiki
Jump to: navigation, search

Arrow about

BallisticNG supports user-created custom campaigns, which can include both vanilla & custom tracks.

These are created via XML files.

Custom campaign XML files contain the information for adding a new entry to the game's campaign. You can use https://codepen.io/thinkfast2008/full/vvKKwq to create one, or write the XML manually. This page will walk you through the structure the game expects and what you need to enter for each element in the file.

Before you read any further, ensure there is a folder called "Custom Campaigns" in your BallisticNG UserData folder (e.g.: "C:\Program Files (x86)\Steam\steamapps\common\BallisticNG\UserData\Custom Campaigns"). If not, manually create it. All of your campaign data will be stored in here.

Arrow quick example

Save the below content as "campaign.xml" in your Custom Campaigns folder. (e.g.: "C:\Program Files (x86)\Steam\steamapps\common\BallisticNG\UserData\Custom Campaigns\campaign.xml")

Tip: you can just click the yellow "Hosted on GitHub" link (below the code) to save it directly:

Directly saving a code snippet on GitHub
Directly saving a code snippet on GitHub

<Settings Name="" />
<Group>
	<Event>
		<Frontend />
		<Awards />
		<EventSettings>
			<Mode Gamemode="Race">
				<Levels>
					<Level Name="Cassandra" />
					<Level Name="Nova Split" />
				</Levels>
			</Mode>
		</EventSettings>
	</Event>
</Group>

Hosted on GitHub

Open the BallisticNG campaign menu to play your new custom campaign:

Custom campaign listed in the campaign menu
Custom campaign listed in the campaign menu
Viewing the events in a custom campaign
Viewing the events in a custom campaign

Arrow campaign structure

Each campaign is built of levels, events & groups.

XML nesting level XML tag name Real-world meaning Real-world example BallisticNG example Description Context
4 Level Track Nuerburgring Cassandra A single track Cassandra, Arrivon Peak, Luna etc.
3 Event Bunch of tracks played in a row WRC Monte Carlo, Monaco "Cassandra Introduction Race" Events contain multiple levels to be played in a row. The player plays Cassandra, then Arrivon Peak, then Luna.

Is then awarded a medal at the end of an event, & is then returned to the campaign menu.

2 Group Tournament WRC Monte Carlo All events in the "Breeze" campaign Groups can contain multiple events.

Groups may require scoring good medals in them to unlock subsequent groups in a campaign.

The 1st group in the "Breeze" campaign contains 3 events: "Cassandra Introduction Race", "Zephyr Ridge introduction race", & "Harpstone introduction race".

The 2nd group in this "Breeze" campaign requires 6 points to unlock.

1 Campaign Championship WRC 2019 "Breeze" A big bunch of groups. The first campaign called "Breeze"

Each group has a defined number of points local to your campaign that you need to unlock it. A bronze medal awards 1 point, silver 2, gold 3 & platinum 4.

Custom campaigns are always unlocked, if you haven't finished the vanilla campaign yet then your custom campaigns will appear under the red unlock notification.

Custom campaigns do not count towards your XP and you can't use them to make levelling up easier or extend the game's levelling system.

Arrow gamemode event restrictions

An event can contain multiple tracks. But "Race" is the only gamemode that supports multiple tracks per event.

Any other gamemode such as "Eliminator" will only let the user play the 1st track in an event.

It's also worth noting that after a user finishes "Speed Lap" on the 1st track for an event, they will be able to continue to any 2nd track of their choosing (even if the 2nd track is not listed in the XML).

Arrow xml examples

1 event containing 1 level[edit | edit source]

<Settings Name="1 event containing 1 level" BarracudaAllowed="False" Video="" FallbackTexture="" />

<Group PointsToUnlock="0">
	<Event>
		<Frontend Name="Cassandra Event" Description="" />
		<Awards BronzeValue="1" SilverValue="1" GoldValue="1" PlatinumValue="1" EasyScore="1" HardScore="1" />
		<EventSettings>
			<Mode Gamemode="Race" ModernPhysics="False" SpeedClass="Zen">
				<Levels>
					<Level Name="Cassandra" />
				</Levels>
			</Mode>
			<Modifiers Hardcore="False" Weapons="True" Mirror="False" ExtraLaps="0" ForcePlayerShip="False" ForceAiShip="False" />
			<Ai Difficulty="Experienced" Count="7" UseSpeedMult="False" SpeedMult="0" />
		</EventSettings>
	</Event>
</Group>

Hosted on GitHub

1 event containing 1 custom track level[edit | edit source]

This campaign uses Cairodrome as the example custom track.

If you see a white picture underneath "event details", ensure that steam is in online mode & that you have subscribed to that track.

<Settings Name="1 event containing 1 custom track level" BarracudaAllowed="False" Video="" FallbackTexture="" />

<Group PointsToUnlock="0">
	<Event>
		<Frontend Name="Cairodrome Event" Description="" />
		<Awards BronzeValue="1" SilverValue="1" GoldValue="1" PlatinumValue="1" EasyScore="1" HardScore="1" />
		<EventSettings>
			<Mode Gamemode="Race" ModernPhysics="False" SpeedClass="Zen">
				<Levels>
					<Level Name="Cairodrome" />
				</Levels>
			</Mode>
			<Modifiers Hardcore="False" Weapons="True" Mirror="False" ExtraLaps="0" ForcePlayerShip="False" ForceAiShip="False" />
			<Ai Difficulty="Experienced" Count="7" UseSpeedMult="False" SpeedMult="0" />
		</EventSettings>
	</Event>
</Group>

Hosted on GitHub

1 event containing 2 levels[edit | edit source]

<Settings Name="1 event containing 2 levels" BarracudaAllowed="False" Video="" FallbackTexture="" />

<Group PointsToUnlock="0">
	<Event>
		<Frontend Name="Cassandra and Nova Split Event" Description="" />
		<Awards BronzeValue="1" SilverValue="1" GoldValue="1" PlatinumValue="1" EasyScore="1" HardScore="1" />
		<EventSettings>
			<Mode Gamemode="Race" ModernPhysics="False" SpeedClass="Zen">
				<Levels>
					<Level Name="Cassandra" />
					<Level Name="Nova Split" />
				</Levels>
			</Mode>
			<Modifiers Hardcore="False" Weapons="True" Mirror="False" ExtraLaps="0" ForcePlayerShip="False" ForceAiShip="False" />
			<Ai Difficulty="Experienced" Count="7" UseSpeedMult="False" SpeedMult="0" />
		</EventSettings>
	</Event>
</Group>

Hosted on GitHub

2 events each containing 1 level[edit | edit source]

<Settings Name="2 events each containing 1 level" BarracudaAllowed="False" Video="" FallbackTexture="" />

<Group PointsToUnlock="0">
	<Event>
		<Frontend Name="Cassandra Event 1" Description="" />
		<Awards BronzeValue="1" SilverValue="1" GoldValue="1" PlatinumValue="1" EasyScore="1" HardScore="1" />
		<EventSettings>
			<Mode Gamemode="Race" ModernPhysics="False" SpeedClass="Zen">
				<Levels>
					<Level Name="Cassandra" />
				</Levels>
			</Mode>
			<Modifiers Hardcore="False" Weapons="True" Mirror="False" ExtraLaps="0" ForcePlayerShip="False" ForceAiShip="False" />
			<Ai Difficulty="Experienced" Count="7" UseSpeedMult="False" SpeedMult="0" />
		</EventSettings>
	</Event>
	<Event>
		<Frontend Name="Cassandra Event 2" Description="" />
		<Awards BronzeValue="1" SilverValue="1" GoldValue="1" PlatinumValue="1" EasyScore="1" HardScore="1" />
		<EventSettings>
			<Mode Gamemode="Race" ModernPhysics="False" SpeedClass="Zen">
				<Levels>
					<Level Name="Cassandra" />
				</Levels>
			</Mode>
			<Modifiers Hardcore="False" Weapons="True" Mirror="False" ExtraLaps="0" ForcePlayerShip="False" ForceAiShip="False" />
			<Ai Difficulty="Experienced" Count="7" UseSpeedMult="False" SpeedMult="0" />
		</EventSettings>
	</Event>
</Group>

Hosted on GitHub

2 events each containing 2 levels[edit | edit source]

<Settings Name="2 events each containing 2 levels" BarracudaAllowed="False" Video="" FallbackTexture="" />

<Group PointsToUnlock="0">
	<Event>
		<Frontend Name="Cassandra and Nova Split Event" Description="" />
		<Awards BronzeValue="1" SilverValue="1" GoldValue="1" PlatinumValue="1" EasyScore="1" HardScore="1" />
		<EventSettings>
			<Mode Gamemode="Race" ModernPhysics="False" SpeedClass="Zen">
				<Levels>
					<Level Name="Cassandra" />
					<Level Name="Nova Split" />
				</Levels>
			</Mode>
			<Modifiers Hardcore="False" Weapons="True" Mirror="False" ExtraLaps="0" ForcePlayerShip="False" ForceAiShip="False" />
			<Ai Difficulty="Experienced" Count="7" UseSpeedMult="False" SpeedMult="0" />
		</EventSettings>
	</Event>
	<Event>
		<Frontend Name="Luna and Cassandra Event" Description="" />
		<Awards BronzeValue="1" SilverValue="1" GoldValue="1" PlatinumValue="1" EasyScore="1" HardScore="1" />
		<EventSettings>
			<Mode Gamemode="Race" ModernPhysics="False" SpeedClass="Zen">
				<Levels>
					<Level Name="Luna" />
					<Level Name="Cassandra" />
				</Levels>
			</Mode>
			<Modifiers Hardcore="False" Weapons="True" Mirror="False" ExtraLaps="0" ForcePlayerShip="False" ForceAiShip="False" />
			<Ai Difficulty="Experienced" Count="7" UseSpeedMult="False" SpeedMult="0" />
		</EventSettings>
	</Event>
</Group>

Hosted on GitHub

Highly customised campaign[edit | edit source]

This custom campaign specifies extra options using XML attributes.

See the content references section for the available customisation options.

This xml creates 2 groups with 1 event in each group. The first group is unlocked by default and contains a Cassandra race, the second one requires 6 points to unlock and features a tournament.

<Settings Name="My Campaign" BarracudaAllowed="False" Video="MyCampaign.mp4" FallbackTexture="" />
<Group PointsToUnlock="0">
	<Event>
		<Frontend Name="Cassandra Race" Description="" />
		<Awards BronzeValue="0" SilverValue="0" GoldValue="0" PlatinumValue="0" EasyScore="0" HardScore="0" />
		<EventSettings>
			<Mode Gamemode="Race" ModernPhysics="False" SpeedClass="Zen">
				<Levels>
					<Level Name="Cassandra" />
				</Levels>
			</Mode>
			<Modifiers Hardcore="False" Weapons="True" Mirror="False" ExtraLaps="0" ForcePlayerShip="False" ForceAiShip="False" />
			<Ai Difficulty="Experienced" Count="7" UseSpeedMult="False" SpeedMult="0" />
		</EventSettings>
	</Event>
</Group>
<Group PointsToUnlock="3">
	<Event>
		<Frontend Name="Tournament" Description="" />
		<Awards BronzeValue="0" SilverValue="0" GoldValue="0" PlatinumValue="0" EasyScore="0" HardScore="0" />
		<EventSettings>
			<Mode Gamemode="Race" ModernPhysics="False" SpeedClass="Zen">
				<Levels>
					<Level Name="Cassandra" />
					<Level Name="Nova Split" />
					<Level Name="Arrivon XI" />
					<Level Name="Luna" />
				</Levels>
			</Mode>
			<Modifiers Hardcore="False" Weapons="True" Mirror="False" ExtraLaps="0" ForcePlayerShip="False" ForceAiShip="False" ForcedShip="Gtek" />
			<Ai Difficulty="Expert" Count="7" UseSpeedMult="False" SpeedMult="0" />
		</EventSettings>
	</Event>
</Group>

Hosted on GitHub

Arrow files

All files are relative to the XML file.

  • MyCampaign.xml - your campaign configuration
  • MyCampaign.sav - the save file generated for your campaign
  • MyVideo.mp4 - the video that will display for this campaign

Arrow content references

Custom campaigns can be customized further using XML attributes.

Campaign customization cheat sheet[edit | edit source]

Below is a table of all attributes used to customize custom campaigns.

Click the table headings below to sort the info to find what you need faster.

XML Tag XML Attribute Description Data type and/or range
Settings Name Campaign name String
Settings BarracudaAllowed Allow/disallow Barracuda use Pascal case boolean (True/False)
Settings Video A video to show when the user has selected this campaign in the menu String (including video extension). E.g.: "MyCampaign.mp4"
Settings FallbackTexture Does not appear to be used by the game. Possibly used to be a picture to show when the Video couldnt be found. Likely a filename (String), including the extension (e.g.: "my-fallback-texture.jpg")
Group PointsToUnlock Number of points required to unlock this campaign.

Unlock points are converted directly from the medal earned. Bronze is 1, Silver is 2, Gold is 3 and Platinum is 4.

Positive number. 0 means the campaign will be unlocked by default.
Event (none) - -
Frontend Name Name of this event. Shown in the UI when it is selected in the menu String
Frontend Description This does not appear to be used by the UI anymore. It was likely a description for an event String
Awards BronzeValue Gamemode value required to be awarded this medal. For example, if the Gamemode is time trial, then this value is the minimum race time required time.

Awards are given at the end of events.

Points are used to unlock subsequent event groups (see the "PointsToUnlock" attribute of the "Group" tag.

Positive integer or decimal (including 0).

Integer example: Gamemode is race, and BronzeValue is 1 (this means 1st place is required to get bronze medal).

Decimal example: Gamemode is time trial, and BronzeValue is 51.5 (this means a race time of 51.50 is required to get bronze medal)

Awards SilverValue See "BronzeValue" attribute description See "BronzeValue" attribute value
Awards GoldValue See "BronzeValue" attribute description See "BronzeValue" attribute value
Awards PlatinumValue See "BronzeValue" attribute description See "BronzeValue" attribute value
Awards EasyScore The target score which ends an Elimination game played on "easy" difficulty.

Note: "EasyScore" is NOT the points awarded to players when completing the event on easy mode - those values are hard-coded by the game.

Positive number (including 0)
Awards HardScore The target score which ends an Elimination game played on "hard" difficulty. Positive number (including 0)
EventSettings (none) - -
Mode Gamemode BNG game mode to use for an event Pascal case string ("Race"/"Time Trial"/"Speed Lap"/"Survival"/"Knockout"/"Eliminator")
Mode ModernPhysics Force classic or modern physics for this event. Classic physics is used in Wipeout 2097. Modern physics is used in Wipeout Omega Collection. Pascal case boolean (True/False)
Mode SpeedClass BNG speed class for an event Pascal case string ("Toxic"/"Apex"/"Halberd"/"Spectre"/"Zen")
Levels (none) - -
Level Name Name of the track, EXACTLY as shown on the track selection screen. This means it is both case & whitespace sensitive. See remarks section about adding custom tracks into custom campaigns. Case-sensitive & whitespace-sensitive string. Can also be used to specify custom track names.

Track names: "Cassandra", "Zephyr Ridge", "Harpstone", "Aciknovae", "Nova Split", "Luna", "Dover", "Ishtar Citadel", "Arrivon XI", "Omega Harbour", "Utah Project", "Marina Rush", "Hydrome Bed", "Arrivon Peak"

Example custom track name: "Cairodrome"

Modifiers Hardcore Enable/disable hardcore mode for an event. This means disabled pitlanes and extra weapon damage. Pascal case boolean ("True"/"False")
Modifiers Weapons Enable/disable weapons Pascal case boolean ("True"/"False")
Modifiers Mirror Load the mirrored version of each track in an event Pascal case boolean ("True"/"False")
Modifiers ExtraLaps extra laps. For a "SpeedClass" of "Zen", 5 extra laps means 10 laps (5+5) Positive number (including 0)
Modifiers ForcePlayerShip Whether to force the player's ship. If this is True, you also need to set the "ForcedShip" attribute on the "Modifiers" element Pascal case boolean ("True"/"False")
Modifiers ForceAiShip Whether to force the ai's ship. It is unknown which attribute name is used to specify the forced AI ship name Pascal case boolean ("True"/"False")
Modifiers ForcedShip Ship name. Potentially case & whitespace sensitive. See "Ships" section
Ai Difficulty Ai difficulty. Potentially case & whitespace sensitive. Pascal case string
Ai Count Number of AI ships to include in an event Positive number (including 0). Leaving this unspecified will add 0 AI ships in each event race.
Ai UseSpeedMult Whether the "SpeedMult" attribute of the "Ai" element overrides the track's speed multiplier Pascal case boolean ("True"/"False")
Ai SpeedMult AI speed multiplier Positive number (including 0). 0 likely means the AI speed will NOT use the track's speed multiplier, and AI speed will be as if the no speed multiplier was specified in either this attribute or the track

Tracks[edit | edit source]

Tracks are referenced by their display name. This is the name that you see on the track selection screen. Custom tracks are supported!

Ships[edit | edit source]

You can only use the game's vanilla ships for campaigns. If you want to force a ship then here is the list of available ships:

   Gtek,
   Wyvern,
   Hyperion,
   Scorpio,
   Omnicom,
   Diavolt,
   Nexus,
   Tenrai,
   Gtekdrag,
   Wyverndrag,
   Hyperiondrag,
   Scorpiodrag,
   Omnicomdrag,
   Diavoltdrag,
   Nexusdrag,
   Tenraidrag,
   Gtekdrift,
   Wyverndrift,
   Hyperiondrift,
   Scorpiodrift,
   Omnicomdrift,
   Diavoltdrift,
   Nexusdrift,
   Tenraidrift,
   Protonic,
   Nx2000,
   Mtechp1,
   Barracuda,
   Caliburn,
   Zoneship,
   PrecisionShip

Gamemodes[edit | edit source]

Any gamemodes registered by the game are available.

If you're using a custom gamemode, then make sure the gamemode handles campaign awards otherwise you won't be able to earn medals to progress.

Arrow troubleshooting

Game behaviour Why its happening How to fix it
  • A different track name is shown than the one specified in the XML file, or
  • After selecting a ship, it loads the track, but then the track is immediately unloaded, the console opens, & a white message starting with "System.NullReferenceException" is shown.
  • The game couldnt read the custom track file on your filesystem
  • Ensure steam is in online mode & that you have subscribed to the custom track.
  • If a different track name is still shown, then ensure the track name in the XML is EXACTLY the same as the filename in your BNG "Custom Track Caches" folder (excluding the extension).
  • E.g.: the track name for the file "GCN - Mushroom Bridge.tch" is "GCN - Mushroom Bridge").
  • Cant get past the ship selection screen. I.e.: upon selection, the game doesn't transition to the track loading screen
  • The track name is correct and was found on your filesystem, but the casing is incorrect
  • E.g.: "gcn - mushroom bridge" instead of "GCN - Mushroom Bridge"
  • Fix the track name casing by updating the track name in the XML to exactly match the filename in your BNG "Custom Track Caches" folder (excluding the extension).
  • E.g.: the track name for the file "GCN - Mushroom Bridge.tch" is "GCN - Mushroom Bridge"
  • Nothing happens after the track loads/black screen shown after track loads
  • The event has no gamemode
  • Update the event gamemode in the XML file.
  • E.g.: <Mode Gamemode="" ModernPhysics="False" SpeedClass="Spectre"> to <Mode Gamemode="Race" ModernPhysics="False" SpeedClass="Spectre">
  • Custom campaign not showing on campaign selection screen
  • Campaign filename is missing the ".xml" extension
  • Soft-locking when trying to play a campaign involving custom gamemodes
  • Custom gamemode(s) are not installed/enabled
  • Ensure the custom gamemode(s) are installed & enabled via the "mods" in-game menu
  • Black rectangle shown in-place of the campaign preview video
The campaign video file was not found, which can be caused by:
  • Misspelled video name (e.g.: "campaing.mp4" instead of "campaign.mp4")
  • The filename doesn't include the extension (e.g.: "my-campaign-video" instead of "my-campaign-video.mp4")
  • The attribute value is an empty string
  • The attribute is missing entirely (e.g.: misspelled attribute name)
  • The video file is not your BNG Custom Campaigns folder
  • The video is not a MP4 file (e.g.: "MKV")
  • Fix video filename in the XML
  • Ensure the video file is in MP4 format
  • Ensure the video file's extension is ".mp4"
  • Ensure the video file is in your BNG Custom Campaigns folder
  • White rectangle shown in-place of the campaign preview video
Steam is in offline mode.
  • Explanation: the campaign video file was found, but the campaign includes a custom track, and custom tracks require steam to be in online mode
  • Restart steam to be in ONLINE mode (instead of OFFline mode)

Arrow remarks

  • Use mp4 campaign video files
  • The element "frontend" has a "description" attribute, but it doesnt seem to be displayed in the game. You can add one in-case a future change occurs that makes the game use it.
  • The xml file encoding doesn't matter (e.g.: UTF-8, traditional chinese, GB etc).
  • Making xml files without syntax highlighting makes mistakes hard to detect. You can use a website if you don't want to install an IDE like Visual Studio Code or Notepad++. Just make sure to wrap all your campaign XML in a "root" tag to make it well-formed after pasting it onto the website, & before hitting the website's "pretty print" button.
  • These xml files are not "well formed", so be careful when using custom campaign files for other purposes (e.g.: a c# mod that parses custom campaign files will need to catch both XmlException and Exception)