Modding Guidelines
Introduction
To edit any script from X3, I highly recommend
X-Studio, from mr.bear. Without this tool, I would never have gone into X3 modding. Also, because Mayhem runs on Litcube's Universe sets of new hardcoded commands, you'll also need this
extra file, required for X-Studio to be able to read the new commands (put the file into the X-Studio root folder).
At some point, you may want to take a look at what scripts are running on what ships. It's easily doable by going into the script editor from your ship console (Shift-C, then S), then activate the following debugging option:
That will add a new information panel into any ship info menu:
As this little article is not a tutorial, I recommend reading the
MSCI Handbook,
MSCI being the name of the scripting language used by X2 and X3. Chapters 4 and 7 are especially useful.
Mayhem 3 has about 800 scripts rewritten or modified. Vanilla scripts always start with an exclamation mark, but some of them have been totally rewritten, like
!move.jump,
!fight.attack.object,
!fight.defend.sector or
!fight.attack.enemiesrange.land. Some others have been added, also prefixed with a "!", because I consider them to be part of the fundamental commands, like
!ship.cmd.flee, or
!ship.cmd.fleet.retreat. Note that the "!" prefix is just a convention: it changes nothing about how these scripts work or interact between each other.
Before going deeper into how Mayhem 3 works, you have to understand that there are two kind of scripts: locals and globals. Local scripts run on a specific object (ship or station), and also on a specific
task, Task 0 being the main task of every ship. Global scripts on the other hand run independently on Task -1. A list of these scripts can be found in the script editor, in the Global Script Tasks menu:
By convention, all Mayhem global tasks that run permanently (ie. in a loop) are prefixed with the "Monitor" keyword. As you can see above, these are very important scripts, like the two Autopopulate scripts that manage the AI strategies concerning ships and stations.
When reading other people code, it may be very useful to understand how scripts interact with each other. You can use a tool like Notepad++ and research the name of the script (without quotes and without the .xml extension) inside the scripts folder, or use the following X-Studio feature:
Script Prefixes
- Vanilla and core scripts start with an exclamation mark, as explained above.
- Mayhem main scripts start with "Mayhem.". Example: Mayhem.BuildShip.
- Library scripts start with "Joubarbe.Lib", like Joubarbe.Lib.GetCommonwealth.
- Menus start with "Menu.", "Menu.PC" being for menus from the Player Console, and "Menu.DWM" for the Outpost Manager (formerly "Dock Ware Manager").
Many scripts are useless, such as all the ones that are prefixed with "!job", "al.", "!lib" and "!plugin". These are remnants from either vanilla, LU or other third party scripts, like MK3 Improved. They don't impact performance.
Mayhem Scripts Overview
Here is a list of some of the most important scripts used by Mayhem ("X" indicates that there are multiple scripts with the same prefix):
- setup.Mayhem runs every time the game loads a new game or an existing savegame. Many features start from here.
- Mayhem.AddBlueprint is used to add a ship type to the list of ships that the player can build.
- Mayhem.AddFullTemplateToBacklog and Mayhem.AddToBacklog are used to order ships, stations and weapons, for both AI and player.
- Mayhem.BuildShip, Mayhem.BuildStation, Mayhem.BuildStationAI.
- Mayhem.Claim, Mayhem.Conquer and Mayhem.IsClaimable manage most of the logic behind sector takeover.
- Mayhem.Cmd.X and Mayhem.Task.X manage all squadrons (AI fleets) and Workers.
- Mayhem.EquipShip is used to instantly equip any ship with either a template's list of components, or with random components if a template of the ship type doesn't exist. This script is rarely used, because Mayhem 3 doesn't cheat (except for Pirates, Xenons and OCV). Instead, Cmd.ShipTemplateOutfit.Dock is used to make both AI and player pay for their templates.
- Mayhem.GameCreator.X manage all the galaxy generation process.
- Mayhem.Init.Templates is the starting point of all templates management. It is called only once at game start, and manages a lot of AI related stuff, like what priority is given to specific stations, what lasers to put in ships, how to compose a squadron, etc.
- Mayhem.InitializeX setup stations. They are called every time a station is built.
- Mayhem.Marine.X and Mayhem.MarineMission.X are respectively managing marines themselves, and boarding missions.
- Mayhem.Mission.X manage the new procedural missions that you may receive when you dock at a station.
- Mayhem.MissionEntry.X manage journal's entries.
- Mayhem.Monitor.X are the main global scripts of Mayhem. They each run inside an endless loop.
- Mayhem.Squadron.X and Mayhem.Worker.X handle squadrons and workers management (global scripts).
- Mayhem.Task.TemplateWhenReady is an important script that setup every ship built from an Outpost, AI or Player.
- Menu.SaturnComplexHub.Install and Menu.SaturnComplexHub.Install.SM handle the Research station menu. It's actually using the former SCH menu from LU.
Adding New Ships
Adding a new ship via TShips (inside addon\10.cat) is not enough to make the ship fully and properly integrated within Mayhem 3. There is no magic in the AI, it has to know precisely what it is allowed to build. This is handled through
Mayhem.Template.Ships. In that file, you'll find some of these lines:
Code: Select all
$class = [M3]
$lists = array alloc: size=0
dim $list = {Argon Nova}, {Argon Notus}, {Argon Venti}, {Argon Eclipse}
append $list to array $lists
This means that when the Argons need an M3 (see
Mayhem.Template.Squadrons if you want to change the composition of their fleets), they will pick a random ship type from this list. So if you want to add a ship that is called "Betty's Fury", first add your ship to the TShips file (I won't detail how to do that here), then modify the script:
Code: Select all
dim $list = {Argon Nova}, {Argon Notus}, {Argon Venti}, {Argon Eclipse}, {Argon Betty's Fury}
Remember that templates are only set at game start. You'll need to call
Mayhem.Init.Templates again in your game if you want the AI to be updated, or start a new game (calling
Mayhem.Template.Ships does nothing).
Research stations should be properly updated as they scan all available ship types every time you open the menu.
The above method is required if you add custom ships to the Commonwealth (+ Yakis). However, if you want to add ships for Xenons, you'll have to edit
Mayhem.Monitor.Galaxy, because Xenons are spawned every X minutes from a random Xenon station, and they are spawned from thin air, and artificially equipped. If you need to add ships for Pirates, you don't have to edit anything,
Mayhem.Task.Station.PirateBase is used on each pirate base to spawn a ship. It uses the script
Mayhem.GetRandomShipType to get a random ship subtype from all existing ones, including the ones you add yourself. However, you need to define pirate ships as Yakis, because there are no Pirate ships in Mayhem 3.
Now the hardest part: ship balance. The following elements have been manually edited:
- Compatible lasers and missiles, also within TCockpits. All ships follow the same logic depending on their class and race.
- Wares list (1 for every ship).
The general characteristics and the performance of the ships have all been automatically edited with an external tool I've developed, that you can find
at this page. The script I'm using in Mayhem 3.0 can be downloaded
here (you'll also need
my custom variables - put everything in the root folder) (FYI,
here is the original TShips I'm applying the script to). However, running this script on your newly added ships will not work, because Mayhem 3's ship balance is based on the physical size of each ship. What you need to do is to go in the in-game script editor, open the script editor menu where all scripts are listed, then highlight
Mayhem.ExportShipSizes, hit R and execute the script on null (global script).
It will take some time to process. When it's finished, the data will have been exported to "addon\t\9978-L044.xml". You need this file to use my JSON tool (it will throw a fatal error if the file is missing). It's also better to include it if you want to share your new ships. However, it's not mandatory, the only downside is that the ship compendium won't display the size of your new ship.
When the JSON tool is finished, it will generate a new TShips inside an "output" folder. Copy that inside a new catalog file (overwriting the default file in 10.cat is a bad idea) via
X3 Editor 2, and you should see consistent statistics in the ship compendium menu.
Note that the script I'm using for the JSON tool has some randomized values in it. That means that every time you run the script, ships will have slightly different stats.
Script Tasks
Here is a list of all tasks ID that Mayhem 3 is using. You should never use these IDs in your own scripts, even though some of these come from Mayhem 2 and are obsolete.
- 201/202: Mayhem.Task.Station.Outpost, Mayhem.Task.Station.ResearchStation and Mayhem.Task.TradingStation
- 1221: Mayhem.Task.Expedition
- 1312: Mayhem.Task.ExploreScan
- 1313: Mayhem.Task.TemplateWhenReady
- 1314: Mayhem.Fleet.ProtectCarrier
- 1315: Mayhem.Fleet.Whip
- 1316: !move.undock
- 1317: !ship.cmd.attack.std (see Mayhem.Fleet.Attack)
- 2044: Mayhem.Task.Claimeable
- 1318: Mayhem.StallEngine
- 1319: Mayhem.Task.Defend.Watch
- 1320: Mayhem.Task.DefendObject.Follow
- 1321: Mayhem.Task.Jump
- 1322: Mayhem.Task.Station.Credits
- 1323: Mayhem.Task.Station.Destruction
- 1324: Mayhem.Task.Station.Autoassign
- 1325: Mayhem.Task.Station.MaxJumpsCheck
- 1326: Mayhem.Task.Station.Autopricing
- 1327: !fight.defend.monitor
- 1328: Mayhem.Task.CarrierRepair
- 1329: Mayhem.Task.OCVVirus
- 1330: Mayhem.Task.MarineMission
- 1331: Mayhem.Task.Station.Repair
- 203: Mayhem.Task.Station.PirateBase
- 1332: !fight.attack.object.stationTactics