UI modding - documentation

[stefanEgo]

The information provided in this thread is superseded by the X Rebirth Wiki page and the XR Modding documentation. Please refer to these two pages for up-to-date documentation on the UI modding in X Rebirth:
Wiki: https://www.egosoft.com:8444/confluence ... birth+Wiki
XR Modding documentation: https://www.egosoft.com:8444/confluence ... dding+Home

Old content:

Official UI modding documentation available here: https://www.egosoft.com:8444/confluence ... dding+Home

With the release of X Rebirth 3.50 we are pleased to announce the introduction of UI modding support to all our modders. The aim of this UI modding support is to grant everybody the same level of flexibility to modify the UI that we have ourselves.

Certain things are, unfortunately, out of the scope of what we can make available to everybody, but whatever we can provide the community with, we will make every effort to do so.

The UI-modding support is, and feels, slightly different compared to modifying other parts of the game engine, such as MD/AI scripting, asset handling, etc. In some cases you will find that the UI features provide you with a lot more freedom, while in other parts you may miss certain functionality. This is especially true, since 3.50 is the first time that we will have more than just our in-house-developers working with the UI engine.

To help you with that, we will not only provide you with some additional documentation to get started, but also include the original Lua source scripts for the standard game UI. You can use these as a point of reference for writing your own scripts. We also decided against enforcing too many restrictions on what we allow you to do when writing UI mods, so that any updates we make available for our own UI changes/updates will automatically be available to you as well.

Bear in mind, however, that this comes with a certain risk of being able to impact the game engine in unintended ways. Specifically, you are more likely to be able to write UI mods which negatively impact the game stability (i.e. introduce crashes, break parts of the UI, negatively impact game performance, etc.) than you would be able to do when writing AI/MD scripts, for instance. This will be especially true for the first number of releases following 3.50 beta 1.

To help you, and all the players out there, to resolve any issues which might show up, we will try out a new approach for reporting bugs and requesting features with regards to the UI modding support:

• We have set up a UI modding support-request thread here (http://forum.egosoft.com/viewtopic.php? ... 96#4497896 (English) / http://forum.egosoft.com/viewtopic.php?t=377588 (German)) which will be monitored by the developers at Egosoft directly. This thread is specifically provided for you to solve any issues/questions/concerns you might come-up with during the weeks to come following the first 3.50 beta.
• We are making our internal bug-tracking system available to you via anonymous access. If you run into a UI modding bug, or have a feature request, you urgently want to be added, you will be able to directly create the issue in the bug-tracker at: https://www.egosoft.com:8443/jira/browse/XRUIMOD . Posting bug-reports/feature requests is done anonymously. You won't need an account to do so. The bugtracker will also provide you with a slightly better detail in feedback on the progress state of reported issues (showing you which ones can be expected to be fixed in one of the following versions or when an issue is being worked on).
• We are opening up our Wiki system and provide you with direct access to the UI modding documentation we also use in-house. This way you always have the latest up-to-date documentation directly available as well as be able to post your comments on the topics: https://www.egosoft.com:8444/confluence ... dding+Home

Please understand, that this solely aims to improve the support we provide our modding community. We however can still not provide support for issues which arise while running a modified game. So bear in mind that whenever you use a mod, there's no assurance that the official support can help with issues which you might run into.

We are aware that there's still a lot of improvements we could get into the engine. A lot of items we had on our own whishlist did not make it into the first Beta. However, we wanted to provide you as soon as possible with these modding improvements so you have a chance of trying everything out yourself and give us your feedback. This allows us to take your feedback into account with the ongoing development of 3.50 (and hopefully also into future versions). We are quite eager to hear from you - so don't hesitate to report bugs or feature requests.

Be assured that none of your feedback will be ignored. Even if something you report does not make it into the current version, it does not mean that the feedback is forgotten. However, please also be aware that there might be reasons for certain feedback/bugfixes not making it into the game for a while (and in some cases maybe not at all). Still, we try to communicate these (hopefully rare) cases to the best of our abilities and explain the reasons for our decision.

As mentioned above, further documentation is available here: https://www.egosoft.com:8444/confluence ... dding+Home

[wysiwyg]

As per Stefan's suggestion here...... (please feel free to delete the post from the other thread if you think it's better placed here)

I thought I would share how I ported my Enhanced Money Transfer mod over to the new system in 3.50 b1 I know most people haven't written mods that patch into the existing UI framework but it should help as a reference as how to do it in general. I won't cover the ui.xml as I think that's already fairly clear - just to reiterate that as things stand the game looks for a single ui.xml file in the mod's root folder. You can also now put your .lua files in the root folder and there's no need anymore to put them in a subst_xx.cat file or use a convoluted path in the xml file to locate them.

So, in the versions previous to 3.50 I was able to simply write a new version of the MoneyTransfer lua file and diff patch the ego_detailmonitor.xml file to replace Ego's version with my own. As of 3.50 b1 I can't do that so I now need to locate the existing (vanilla) menu and "hook" my functions into it. Here's how:

First I make a local empty table to hold a copy of the vanilla MoneyTransfer dialog:

Code: Select all

local emt_menu = {}

I'm also going to make a table to store my collection of functions as this is how I like it (makes debug and cleanup a lot easier)

Code: Select all

local Funcs = {}

Now, here's the important bit (with comments):

Code: Select all

local function init()   -- This function runs at game startup to load menus

	-- iterate over the master "Menus" table to find the menu we want to plug in to
	-- Note that "Menus" is THE master table that holds a live copy of all XR's menus/dialogs

	for _, menu in ipairs(Menus) do     -- note that the underscore is simply a placeholder for an ignored variable 

		-- We're looking for the menu called "MoneyTransferMenu"

		if menu.name == "MoneyTransferMenu" then				

			-- We found our menu so let's first make a local copy of it that we can use, for example if we need to call any Helper functions
			-- or maybe access any passed parameters. In my functions below I can now access passed in parameters as e.g. emt_menu.param1

			emt_menu = menu

			-- Now we hook in our own functions to replace the originals

			menu.onShowMenu = Funcs.EMT_onShowMenu
			menu.onUpdate = Funcs.EMT_onUpdate
			menu.onSelectElement = Funcs.EMT_onSelectElement
			menu.onCloseElement = Funcs.EMT_onCloseElement
			menu.cleanup = Funcs.EMT_cleanup
         break      -- we found our menu so we can break out of the for loop as we don't need to carry on looking anymore
		end
	end
end

Job Done - well almost - we still need to define our own functions below, so (without all the boring details)

Code: Select all

Funcs.EMT_cleanup = function()
	.........
end

Funcs.EMT_onShowMenu = function()
	...........
end

-- Note here that I'm using the onUpdate function so I need to set an update interval - I access this via my local copy of the vanilla menu
emt_menu.updateInterval = 0.5
Funcs.EMT_onUpdate = function()
	..............
end

Funcs.EMT_onSelectElement = function()
	...........
end

Funcs.EMT_onCloseElement= function(dueToClose)
	.........
end

Finally, call the init() function and the mod is patched into the original menu framework

Code: Select all

init()

Remember that if you wish to call any of the functions in the member table (Funcs) locally i.e. inside the mod then use the : operator e.g.

Code: Select all

Funcs.LocalFunction = function()
	local foo = 5
	return foo
end

bar = Funcs:LocalFunction()
-- bar is assigned the value 5

Hope this helps
Wysi