BNW Lua API Reference

(Yet another) BNW Lua API Reference

Q1) So how is this one different?
A1) The others are either based on the out-of-date reference originally provided in the SDK, or by trawling the Lua game code. This one has been compiled by parsing the C++ code that forms the Lua API.

Q2) So it's 100% accurate?
A2) No - the process is mostly automated, but still requires some human intervention, so it can never be guaranteed to be 100% accurate.

Q3) So what's the advantage?
A3) It's in XML, so with a few well-crafted XSL transforms you can have it in any format you want, eg the attached spreadsheet. And it's searchable.

Q4) Will you be doing the same for G&K and vanilla?
A4) No - the process is just too boring. BNW is regularly on sale ... go and buy it!

Q5) Will you be adding your DLL additions?
A5) Possibly

Q6) What if I find an error?
A6) Fork the repository, make the change to the required LuaXyz.xml file and push it

Q7) What if the error is in the spreadsheet?
A7) The spreadsheet was generated from the xml (the primary data source), so change the xml (see Q6), and then regenerate the spreadsheet

Q8) Will you be adding links to the game core Lua files where the methods are used?
A8) No - that's what powerful search tools like Agent Ransack are for!

The attached zip contains a MS-Excel spreadsheet with one tab per object.
The extracted xml and processing code is on GitHub


Each tab contains one row per method, formatted as follows


Required parameters are formatted as
and optional parameters as

Types that look like XyzTypes (eg PlayerTypes, BeliefTypes, TeamTypes, etc) are references to C++ enums - they can be treated as integers

Entries highlighted in red are known to be buggy (or just not implemented!)

Enjoy

W

Calling convention
For methods marked as static="true" use dot notation, pObject.Method(params)
otherwise use colon notation, pObject:Method(params)

A note on return values

void - method returns no value

nil - method doesn't actually put anything on the return stack, but informs Lua that it does! At best, you'll get nil, at worst some random junk that was on the stack.

int - a single integer, etc

int, int, bool - a list of three values (two ints and a bool)

int, ... - a list of ints of indeterminate length, assign to an array and iterate over them

(int) - an array of ints

((int)) - an array of arrays of ints

{x, y, z, w} - a hash with given keys

{Player, Plots({X, Y})} - a hash where the Plots entry is an array of hashes each containing an X and Y entry

etc

Ooooh, very handy! Thank you

Cheers mate.

This quick reference will make life a little easier writing all that glorious spaghetti code

OP updated

Spreadsheet now contains return value and parameter details

I'm in the process of putting the extracted xml and processing xslts onto GitHub - here

Adding this spreadsheet here, as it's related

BNW GameEvents as extracted from the C++ source code - same caveats apply, mostly automated but some human intervention means I cannot guarantee 100% accuracy

I'll add these to GitHub at some point

And the LuaEvents - these are standard across all versions - Vanilla, G&K and BNW

Only four are really of any interest to modders

* AdditionalInformationDropdownGatherEntries and RequestRefreshAdditionalInformationDropdownEntries as these are the events used to add entries into the "Diplo Corner Additional Menu"

* EnemyPanelHide and ProductionPopup can be useful to detect UI state changes

Hmm...related to the "100% accuracy disclaimer": for GameEvents.CityCaptureComplete I use these arguments: (iOldOwner, bIsCapital, iX, iY, iNewOwner, iPop, bConquest, iUnknown).

Where I have "iNewOwner" you have "iCity" but from every time I've used the event that 5th argument always seems to be the ID# of the victorious player and not anything related to the city itself. I think the modwiki is also showing it as a PlayerID#, but what the modwiki is showing is not always significant.

On the other hand, it looks like I finally figured out what in the Firaxis that final argument is for

Yep, it should be iNewOwner for the 5th parameter

(One of the joys of CvPlayer, CvCity, CvUnit et al all having a GetID() method!)

The 139 new events add by DLL - Various Mod Components (v80) (and also the CP) can be found attached to this post

GitHub updated as per LeeS' correction and also created repo for the events