Lua Module Reference

[EmperorFool]

I went through the Assets folder and listed all folders that contain Lua files and the files themselves in the Civ5 wiki's Lua Reference page. I wrote basic descriptions of what each folder holds after skimming through some modules. Hopefully as we work with each file we can fill out the file's specific page.

As I wrote at the top of that page, it lists only the Lua modules (.lua files) under Assets. It does not cover the classes and functions exposed to Lua by the SDK such as ContextPtr, Player, etc. When I get some time, I may use grep to create a list of the classes and maybe the methods that have been used in these Lua files. We'll need the C++ SDK to get the full picture, however.

 

[rackam77]

Thanks a lot ; )

 

[Maniac]

Is there no equivalent for Civ4's CvEventManager, meaning the only modding of game rules that is possible before the C++ code is released, is XML?

 

[Nercury]

I suggest every modder to add what they learned. I already created page for AssignStartingPlots.lua

 

[EmperorFool]

@Maniac - I don't have the code here at work, but in a way, yes. You register event callbacks directly with an object exposed by the SDK. One example I can think of off the top of my head is in the Assets / Automation folder. The modules in there all have the same pattern, are short, and register a single event callback (EndFrame IIRC).

This is the general form, though the registration line is totally wrong. You should be able to work it out from any one of those three modules. Now, which events are available? Good question. I think someone created a list of the known ones in the wiki. I don't know how you figure out the parameters each receives without finding an existing callback for each in the Civ5 code.

function handler() 
    ...
end

Events.Something.Register("EndFrame", handler)

 

[Nercury]

Added some info about GameInfo.

 

[Maniac]

@Maniac - I don't have the code here at work, but in a way, yes.

Yes, there is no equivalent for CvEventManager, or yes, it is possible to mod game rules with Lua?

You register event callbacks directly with an object exposed by the SDK.

I'm afraid I barely understand this sentence.

Assuming one would know the input for a function [such as SerialEventImprovementCreated] and how the registerline should look like [I guess one can't just replace Automation.SetEventFunction("EndFrame", OnEndFrameEvent) with Automation.SetEventFunction("EndFrame", SerialEventImprovementCreated) or something?], can one just place a new Lua file anywhere in the Assets folder, and the game will read it?

 

[EmperorFool]

Yes, there is no equivalent for CvEventManager.

This one. LuaEvents is how you register functions to be called (callbacks) when an event is fired. A callback is a function that you want to be called. You say, "Hey, when X happens, call me back so I can do Y."

Assuming SerialEventImprovementCreated is the name of the event you would do something like this:

function onSerialEventImprovementCreated ( ... )
    ...
end

LuaEvents.SetEventFunction("SerialEventImprovementCreated", onSerialEventImprovementCreated)

Again, this is conjecture on my part as I have barely looked at the code at this time. I haven't written any Lua code yet.

 

[manar]

I went through the Assets folder and listed all folders that contain Lua files and the files themselves in the Civ5 wiki's Lua Reference page. I wrote basic descriptions of what each folder holds after skimming through some modules. Hopefully as we work with each file we can fill out the file's specific page.

As I wrote at the top of that page, it lists only the Lua modules (.lua files) under Assets. It does not cover the classes and functions exposed to Lua by the SDK such as ContextPtr, Player, etc. When I get some time, I may use grep to create a list of the classes and maybe the methods that have been used in these Lua files. We'll need the C++ SDK to get the full picture, however.

Hi . I ran the lua files against doxygen and generated some documentation and reference , it's not perfect by any means* but could be interesting for fast lookups** .

Same as for EmperorFool , only the functions declared in the lua files are referenced , it does not cover the classes and functions exposed to Lua by the SDK such as ContextPtr, Player, etc

* Variables are not pretty , they show what they are set to in the docs , unfortunately I have too little time to work on how they are displayed at the moment .
** Ie. You can search through the interface for "On" and you get a list of events and the Lua file where they are .

 

[Maniac]

This one.

Thanks! And can one simply place a file with that function anywhere in the Assets folder, and it will be read by the game?

 

[dajt]

This is an example of a lua-only mod - no changes to the UI and no UI elements or DB updates defined in the XML.

You need to tell the game to load and run your lua code using the modinfo Content entries. For example, in modbuddy I created a lua file called "Lua Script1.lua" and in the mod's property editor, Content tab, I added the following:

Type: InGameUIAddin, Name: AutoUpgrade, Description: x, FileName: Lua Script1.lua

Then in LuaScript1.lua I have

function TechAcquired()
	local player = Players[Game.GetActivePlayer()];
	local pTeam = Teams[player:GetTeam()];
	local pTeamTechs = pTeam:GetTeamTechs();
	
	eRecentTech = pTeamTechs:GetLastTechAcquired();
	if (eRecentTech < 0) then
		return;
	end

	if (eRecentTech == eLastTech) then
		return;
	end
	eLastTech = eRecentTech;

	local pTechInfo = GameInfo.Technologies[eRecentTech];
	if (pTechInfo == nil) then
		return;
	end

	szText = Locale.ConvertTextKey( pTechInfo.Description );
	print( "Acquired tech: " .. szText );
	for v in player:Units() do
		if (v:CanUpgradeRightNow() and not v:IsBusy()) then
			szText = Locale.ConvertTextKey( v.Description );
			print( "Can upgrade: " .. szText );
		end
	end
end
Events.TechAcquired.Add( TechAcquired );

When the game loads the mod it runs the above code. Only the last line actually does anything at load time: it tells the game it wants the TechAcquired function called whenever a new technology is available to the player.

I've just been grepping through the game's lua scripts to see what events are available and how to register for them.

I can't help thinking the game will slow down badly if too many mods register for common events (eg end of frame!) and worse if those mods are badly written.

Regards,
David.

 

[smellymummy]

I can't help thinking the game will slow down badly if too many mods register for common events (eg end of frame!) and worse if those mods are badly written

if you have debug on, you can see the lua memory usage. it can climb up fast but so far it's better, in my experience, than how a civ4 game would run with a lot of python

 

[Mannu]

David,

Thanks for your post, that was very helpful. Do you know of a list of the valid types to enter in Content or where I might find such info?

 

[smellymummy]

David,

Thanks for your post, that was very helpful. Do you know of a list of the valid types to enter in Content or where I might find such info?

for types, when you have the game running, start the tuner, go to the table browser tab, find the [+]*Types button and expand (might have to change state type, the drop down menu in the top left). it will show index and names of types. the types are also listed in the "sdk path/ModBuddy/Help/Civ5LuaAPI.html" under Enums. table browser for the quick index or the html for the doc it depends on what you need to look for

 

[SamBC]

for types, when you have the game running, start the tuner, go to the table browser tab, find the [+]*Types button and expand (might have to change state type, the drop down menu in the top left). it will show index and names of types. the types are also listed in the "sdk path/ModBuddy/Help/Civ5LuaAPI.html" under Enums. table browser for the quick index or the html for the doc it depends on what you need to look for

This advice seems somewhat meaningless... neither of those sources seems to give any information as to the types that can be used for Lua files in the content list of a mod. I'm not even sure I'd expect them to.