Colour By Race

• Colour By Race is an AL plugin for X3:TC, X3:AP and X3:FL which colours the names of ships, stations across the galaxy. It makes for a cool looking and easier to parse sector and universe map.
  • Most objects only have part of their name coloured, usually the name of their race or corporation.
  • New ships and stations will have their names coloured as they spawn.
  • Default colours are editable in the t file.
  • Object names will change colour when they change owner or when a disguised smuggler is discovered.
• As of version 2.0.0 you can also colour the names of sectors in X3:FL only. Sector colouring is activated as a separate AL plugin so you can use it standalone or alongside colouring ships & stations.
  • FL version of Colour By Race requires the latest version of Cycrow's unofficial patch.
  • Border sectors can be set to use different colours to core sectors.
  • Sector colour will automatically change when the sector changes owner.
  • Thanks to Cycrow's unofficial patch, coloured sectors are still searchable in the universe map search bar!
• More screenshots of Colour By Race in action at this Imgur gallery.

Install

Download the latest release from Github. You probably want to download the .zip file not the .tar.gz file. Unzip the download and copy paste files into the X3/addon/ folder. Files in the scripts/ folder go into the scripts/ folder. Files in the t/ folder go into the t/ folder.

Launch the game and load a save or start a new game. Navigate to Main menu->Gameplay->Artificial life Settings and activate "Colour By Race" and/or "Colour By Sector".

Farnham's Legend

If installing for Farnham's Legend put the files into the X3/addon2 folder instead of the X3/addon folder.

Optional Files

Optionally you can also use the following optional files. They are included in the zip file under optional/.

• Modified 8513 translation files for Pirate Guild 3. PG3 dynamically renames pirate stations which overwrites any previously set coloured names. I've modified PG3's t files so that pirate stations will include colour in their name. Paste these files into your X3/addon/t/ folder overwriting existing files if necessary.
• Modified ship naming script plugin.mbase.create.ship.name.xml for Military Base Response Revamp. Colours the race name during ship creation. Without this you have a very small chance of seeing MBBR ships uncoloured for half a second after creation.
• Modified ship naming script plugin.salv.al.ship.cfg.xml for Salvage Commands & NPCs. Colours the race name during ship creation. Also added setting of pilot name, skill, morale and aggression and addition of Explorer Command software.

Uninstall

Colour By Race creates a global variable as part of its initialisation. It deletes the global as part of deactivation. To make sure the global isn't recreated when you load a save, follow these steps.

• Launch the game and load your save.
• Navigate to Main menu->Gameplay->Artificial life Settings and deactivate the plugin.
• Save your game.
• Delete the plugin files.
  • Open the X3\addon\script folder in Explorer and delete the relevant scripts. They all contain plugin.jj.colour.by.race as part of their filename.
  • Open the X3\addon\t folder and delete the 9964 and 9965 t files.
• Load the save you made after deactivation. Colour By Race should be gone from the Artificial Life menu and its global will be missing from this save.

Debug

As of v2.0.0, Colour By Race has a dedicated script for activating debugging. To log debugging information run this MSCI code.

= [THIS]-> call script 'plugin.jj.colour.by.race.set.debug' :

Info will be logged to log09964.txt. By default this file is saved to C:\Users\Username\Documents\Egosoft\X3FL or similar. Your installation may differ. Note that the plugin will generate a large amount of data. The debug file can reach 25MB in size after just a few hours gameplay.

You can disable debugging by running the same script with the "disable" flag set to true:

= [THIS]-> call script 'plugin.jj.true.relations.set.debug' : disable=[TRUE]

Deactivating Colour By Race in the AL game menu will also disable debugging.

Bugs

Found a bug? I'm keen to hear about it. Report it as a Github issue or on the Egosoft forum thread. I'm particularly keen to hear about uncoloured ships or stations that should be coloured.

Default Race Colours

If you want to change a race's assigned colour you can edit the entries in the 9964 translation file. No colours are hardcoded in script files. The t file contains extensive comments documenting settings.

Race	-	Colour	Code	Image Example	Note
Argon		Blue	\033B
Boron		Green	\033G		Example of colouring shortened race name.
Split		Magenta	\033M		Example of an object without a race specific string. In this case I simply colour the first word of the name.
Paranid		Orange	\033O
Teladi		Yellow	\033Y		Corporation names are coloured in the same way as a race.
Pirates		Red	\033R
Goner		Blue	\033B
Independant		Cyan	\033C		Currently the XRM Privateer Trading Post and Strong Arms Weapons Dealer are the only "independant" race objects coloured.
ATF		White	\033W
Terran		White	\033W		A rare example of an object where the entire name is coloured. Some stuff just looks weird partially coloured or prepended with a race name.
Yaki		Red	\033R		Example of an enemy ship. X3's standard red text colour for an enemy contrasts with the \033R highlight red colour.

Default Farnham's Legend Corporation Colours

In FL, corporations exist as their own races independant from their parent races.

Race	-	Colour	Code	Image Example	Note
OTAS		Blue	\033B
Terracorp		Blue	\033B
Atreus		Green	\033G
NMMC		Yellow	\033Y
Strong Arms		Magenta	\033M
Beryll		Blue	\033B	-	Beryll is not yet implemented in Farnham's Legend.
Duke's		Red	\033R
Darkspace		White	\033W
Industritech		Orange	\033O	-	Industritech is a Paranid corporation not yet implemented in Farnham's Legend.

What is coloured and what isn't

• Objects that are coloured:
  • Most ships.
  • Fighter Drones.
  • Stations:
    • Shipyards.
    • Docks including Equipment Docks, Trading Docks and Stock Exchanges.
    • Corporate HQs.
    • XRM Weapons Dealers.
  • Sector Names.
• Objects that are not coloured:
  • Any player property is untouched.
  • Factories.
  • Most freight drones unless they have a race name.
  • Jump beacons.
  • Xenon or Kha'ak (by default - you can change this). I saw little value in colouring ships which are always hostile.

How It Works

When the plugin is activated, it goes through all the ships and stations in the universe and adds colours to their names. This process is repeated every time you load a saved game.

When renaming an individual object, the plugin checks its name against an array of strings. If one of these strings is detected, that part of the name is colored. For example, for Argon ships, the plugin checks for the following strings: "Argon", "A.", "OTAS", "Terracorp", "Jonferco", "Plutarch", "Beryll," and "Privateer". Once an object is coloured the plugin sets a local variable to prevent it from being recoloured and to allow it to be reset if necessary.

After activation, the plugin must detect new objects so their names can be coloured. In Farnham's Legend the plugin uses [SIGNAL_CREATED] signal to detect new ships & stations. This approach is much more performance-friendly than manually checking the universe for new ships regularly.

Once a new object is detected it is coloured once, then after about half a second it is coloured again and after a longer wait of about 15 seconds it is coloured a third time. This is to ensure that a colouring script runs after any creation scripts that might overwrite the name of the object. This is particularly an issue with mods such as Military Base Response Revamp and Pirate Guild 3.

Albion Prelude & Terran Conflict

[SIGNAL_CREATED] is not available in Albion Prelude and Terran Conflict so we use [SIGNAL_CHANGESECTOR] instead. This signal does trigger for many objects as soon as they are created but it has a few significant shortcomings.

• [SIGNAL_CHANGESECTOR] triggers every time a ship goes through a gate.
• Stations do not trigger [SIGNAL_CHANGESECTOR] or any other signal upon creation.
• Ships that spawn in docking bays of carriers or stations do not trigger [SIGNAL_CHANGESECTOR] until they leave the dock.

To mitigate these issues, the plugin takes the following steps:

• We avoid going through the colour process each time a ship triggers [SIGNAL_CHANGESECTOR] by checking the local variable assigned to the ship but even this quick check leads to some wasted CPU cycles.
• Checks the universe once every 30 minutes for new unnamed stations and dockable ships. Although not ideal, this approach does not waste a significant amount of CPU.
• Does the same check when the player changes sector.
• When [SIGNAL_CHANGESECTOR] triggers for a lasertower, checks if it has a homebase to colour. This is because lasertowers are often spawned to guard stations, so if a lasertower is respawning there's a reasonable chance that the homebase it was guarding has also recently respawned.

The limitations of AP and TC mean you'll occasionally see an uncoloured ship or station, but the additional checks performed by the plugin should make this a rare occasion.

Compatibility

• Terran Conflict - Yes.
• Albion Prelude - Yes.
• Farnham's Legend - Yes.
• X3 Reunion - No.
• XRM - Yes, I originally developed this while playing on an LxXRM installation. The plugin includes code to handle several XRM specific objects.
• Litcube's universe - I've never played it, so I'm not sure. Try it and let me know!
• Military Base Response Revamp - Yes, especially if you overwrite MBBR's ship naming script with the included optional script.
• Pirate Guild - Yes, though station names will be overwritten so I strongly advise the optional included translation files.

Ancillary Stuff

Languages

• Russian (Provided by Alexalsp)
• English (my native language)
• German (checked by Olsch)
• French
• Spanish
• Italian
• Czech
• Polish
• Japanese

Why an X3 mod in 2023?

Because I'm an idiot.

Thanks

• Thanks Egosoft for making a great game.
• Thanks Cycrow who saw my proof of concept and wrote me a primer on global signals in X3.
• Thanks Olsch for improving my dodgy German translation.

Changelog

2.0.1

• Added Russian translation provided by Alexalsp.
• Added Japanese translation.
• Improved messaging of wrong version of FL unofficial patch including adding message to plugin description in AL menu.

2.0.0

• Added dynamic colouring of sector names available only in FL.
  • Sector colouring is activated as a separate AL plugin so you can use it standalone or alongside colouring ships & stations.
  • Sector colours are editable in the 9964 t file set as a red, green and yellow value to be combined into an RGB colour. By default these RGB colours are identical to the colours used for ship & station names.
  • Border sectors can be set to use different colours to core sectors. By default they are the same. You can set the border sector colours for individual races manually or set a general % value to lighten/darken the core sector colour.
  • Colour By Race in FL now requires the unofficial patch by Cycrow as sector colouring requires some of the new scripting functions.
• Rewrote plugin to start a task on new ships and station for rechecking their names instead of adding them to a global array to be checked on a timer. More elegant and more efficient on CPU and less likely to show uncoloured objects while waiting on 180 second timer.
• Changed to use SIGNAL_CREATED instead of SIGNAL_CHANGESECTOR to detect new ships for colouring in FL. SIGNAL_CREATED is called once per ship only, meaning reduced CPU load.
• Improved reset functionality.
  • Added check on game load to see if settings are changed from the last session due to a change in the t file. If a change is detected, the plugin will inform the player and reset and recolour all ships, stations and/or sectors to match the new settings. This way the player can change settings without needing to deactivate and reactivate the plugin - though this method is still possible.
  • The reset and recolouring is run in parallel for a seamless transition from the user's point of view - user won't see the entire universe uncoloured for a few minutes.
  • If a version update is detected, the plugin will inform the user of the update and reset and recolour ships, stations and/or sectors.
  • Old data from a previous game session is now stored to be used for any reset deemed necessary on session start. It's then deleted.
  • Pirate Guild 3 Mob Bosses and special XRM stations such as "Farpoint Station" are now reset properly.
• Added script to check for short prepend on objects with short names and replace with the long prepend. This is run once on version upgrade. This was a mistake introduced to a couple of objects in earlier version of plugin. Only seen it in German translation so is fairly rare.
• More informational messages. Short messages now appear as a game tip in FL and AP.
• Changed Terran colour from "silver" to white as I can see it better. If you prefer to revert to silver, you can edit settings in the 9964 t file.
• t file improvements.
  • Separated True Relations & Colour By Race into separate t files. 9964 is the main t file. 9965 now only contains hard coded coloured names of stations and is not used by FL as we can immediately detect creation of stations with SIGNAL_CREATED.
  • Added more documentation comments to the t file to explain editable settings.
  • Moved some hardcoded settings into t file so they can be edited.
    • XRM command ship job IDs and relevant sector string IDs.
    • References to object names to be prepended with race name.
  • Replaced "Pirate Ship" entry at id="3771" with original uncoloured string.
  • Added some strings to German t file to ensure an entire word is coloured in stations. For example "Piratenhafen" was only getting "Piraten" coloured which looked odd.
• Added check to see if plugin is running processes. This stops the plugin from running two intensive processes at the same time and prevents breakage from conflicting processes. For example deactivating while init process is running would break things and vice versa.
• Added handling of OWNER_CHANGED signal to rename a ship when its owner changes.
• Improved debugging logging
  • Added dedicated script for enabling debugging - plugin.jj.colour.by.race.set.debug.
  • Debug now set to text number (9964) rather than boolean true.
• A bunch of refactoring including some functions from jj.colour.by.race to jj.lib.

1.3.1

• Prevented search substrings from being deleted when processing a plugin update. This bug prevented the galaxy from being reset so objects could be recoloured from a "blank slate".

1.3

• Improved plugin deactivation. Plugin will now remove the colour from the coloured part of the name of all ships and stations in the galaxy and remove all local vars and global vars. It will be as if Colour By Race was never installed.
• Setup [SIGNAL_CREATED] for stations in FL. In FL stations will now be coloured as soon as they appear in the universe.
• Improved detection of FL. The plugin would fail to detect FL if X3 was running unofficial patch version 1.3.6 and later. Amongst other things, this would leave corporation ships uncoloured.
• Changed prepending of ships without a race substring to colour. Previously the plugin queried a list of approved jobs to prepend with a race name. This was cumbersome, it's quicker to query jobs which shouldn't be prepended with a race name. Currently the only job we make sure not to prepend is the UFO Unknown Ship job 8660 and any drones.
• Setup a feature where a set of station-only search substrings will be searched before any others. For example I added "Boronen" to this set for the German translation which will be searched and coloured before "Boron". These strings are set with IDs from x50 to x60 where x is the race ID. So for example strings 450 to 460 for the Paranid.
• Fixed some t file typos
• German translation:
  • Added "Militärischer" to German translation substrings and made sure it gets coloured before Militär.
  • Added "Herzogs" as a substring to search for Duke's
• Added descriptions to all script files.

1.2.2

• Added German translation - thanks to Olsch for checking and improving my initial attempt.
• Added ability to add strings to t file to check for stations only, but checked before other strings - needed for German translation which has masculine and feminine noun modifiers.
• Made a dubious attempt at other French, Spanish, Italian, Czech and Polish translations. I took these translations straight from Google translate.

1.2.1

• Forgot to version up event file to 1.2

1.2

• Now compatibile with Terran Conflict.
  • Wrote alternate code for command get race id for race. This was the only plugin code which TC couldn't handle.
• Deleted extraneous files player.xml and init.xml
• Lasertower activation timer fix now called on lasertower change sector signal
• Now only check XRM stations if XRM is activated - was renaming McCallum station but couldn't find string.

1.1

• Now compatibile with Farnham's Legend.
  • Added FL corporations as races to search for. Includes conditional script which checks which engine version.
  • Added prepending of ship & station names with race name if none found for certain jobs. Uses shortened name if name length already quite long.
• Fixed bug where lasertower activation timer would be saved into the name.
• Added/Fixed search strings to be coloured:
  • FL - corps, The Marauder, Nikkonofune
  • Terraformers, Exterminator, ATF Orbital Defence Station
  • fixed Beryll string
• Added script to remove the local variable on all ships and stations. This is used when updating the plugin so we can re-check the galaxy and when the plugin is deactivated.

1.0

• Initial Release