[Wiki] New Lua and UI Reference! Beta version

D

DonQuiche

Emperor
Joined
May 23, 2011
Messages
1,122
Rejoice modders, because we now have a new and exhaustive Lua and UI Reference section on the CivFanatics wiki!

Ongoing. As I am writing this post, my little bot is uploading those thousands of pages. This will take many hours in order to not saturate the wiki server, so do not worry about missing links for now. This will probably be over tomorrow.

What is this about? The bot is mainly able to generate exhaustive signatures with a consistent type system for about every function and method signature in the game. It also extracts samples from the game source code and display them on the corresponding functions pages.

What is this not about? This is not about me turning from a developer into a technical writer and writing thousands of pages by hand. I will manually write and complement a few types and pages but nothing more. I am a coder, not a writer. The collaborative nature of a wiki is here to take care of the rest.

Beta version. Until October 15 2012 this wiki section will be in beta version. This means that until this date I may use my bot to regenerate the pages anytime and without any notice. So do not waste time editing those pages for now as your changes would be lost.

I want your feedback! Do you see any problem? Some bug? Do you have suggestions?

What about the old pages? They are still there and I will scan them in the days to come in order to extract the few informations they have and add them to the new wiki. Meanwhile, the old version is available here.

EDIT: For more informations about the terminology and how the pages were generated, see the Civ5 API Reference FAQ.
EDIT: There are some display bugs with code samples and examples. The syntax colorization is not the one expected. This requires a wiki extension to be fixed, I will discuss it with Ainwood.
EDIT: Anyway, the code samples are bugged: because of recent changes I made, the variables declaration involved in a function call are no longer listed before the call, I will fix this.
 
thank you for this :goodjob:
 
ok, moved.
 
I do agree it could fit in the "tutorials" section but you could as well say it should be in the "Lua and SDK" section since it is mostly about Lua.

In the end I think that what matters is that this post is an announcement, not a resource you will search for in three months, and so it does not fit in the tutorials section imo. Now I choose the main section over the "SDK/Lua" because it is the one that offers the best visibility and it fits an announcement better.
 
Cheers for doing this DonQuiche, it's an awesome reference and will help me immensely over the summer. My only suggestion, and I'm not sure if this is still in the works or just wasn't on the pages I checked, but I figure code out by looking at other code. For example, when starting wonders I looked at Ambrox62's wonders for tips on how to do stuff. I'd like to be able to see snippets of LUA code which could, essentially, be cut into a LUA file and work properly ingame, just to get an idea of how to actually use the code. I understand this would be a lot of work, but from the sound of it you've got a bot working on it, so I'm not sure if that would speed it up or something? Nonetheless, you've done a fantastic job on this, and you deserve a mountain of virtual cookies
 
Hello Pouakai and thank you for the cookies. :)

Manually writing code snippets for everything or even a substantial part of functions is indeed out of question. However the bot collected samples from the Firaxis source code and display them on functions' pages. Let's look at an example...

So let's say you know nothing about wonders. If you look at the bottom of the page, you will see Category:Civ5 Buildings API. Let's say you pick City:SetNumRealBuilding in the list.

This page offers a few code samples, such as:
Code: 
TurnsRemaining.lua (G&K)
DLC/Expansion/Scenarios/FallOfRomeScenario/TurnsRemaining.lua 
0972: pCity:SetNumRealBuilding(GameInfoTypes["BUILDING_MONUMENT"], 1);

TurnsRemaining.lua (G&K)
DLC/Expansion/Scenarios/MedievalScenario/TurnsRemaining.lua 
0827: pVaticanCity:SetNumRealBuilding(iBuildingID, 1);
1084: capital:SetNumRealBuilding(iBuildingID, 1);
1130: cityState:SetNumRealBuilding(iBuildingID, 1);

Besides, on the signature the reader is informed that the first argument has the type BuildingType. If you look at this page you will see:
* A statement that this is just an integer for the ID column of the Buildings table.
* The list of (ID, Type) pairs in this data table.
* Automatically generated examples of how to get an ID from the Type, and how to get the text description for a given ID.

Code: 
Here are different ways to query the database to retrieve the ID from the type. Those examples will return and assign the integer value -1. See also GameInfo.
local id = GameInfo.Buildings.BUILDING_AMPHITHEATER.ID
local id = GameInfo["Buildings"].["BUILDING_AMPHITHEATER"].ID
local id = GameInfo.Buildings{Type="BUILDING_AMPHITHEATER"}().ID

Alternatively you could use the ID or the type to retrieve the value of the Description column. Those examples will return and assign the value TXT_KEY_BUILDING_AMPHITHEATER.
local description = GameInfo.Buildings[-1].Description
local description = GameInfo["Buildings"][-1]["Description"]
local description = GameInfo.Buildings{ID=-1}().Description

I am under the impression that there are already enough examples on how to work with buildings and wonders on those pages. Do you think there should be something more?

Now what I plan to change is:
* There is a bug in the samples: the iBuildingID variable declaration/assignment should be displayed but it is not. I will fix this. Well, it may not always be possible when the missing variables are functions' parameters: I would need to pick one of the parent cal and this would require a lot of work so no promise.
* I may consider scanning popular mods besides of the Firaxis source code, in order to get more useful samples.
* Nitpicking: when a file is taken from a DLC, it should be mentioned in the sample header along with the game version.
* In the automatically generated examples in BuildingType, add an example with GameInfoTypes.
 
Looked over the Lua introduction (not til the end, but 2/3 I guess). I neither have Civ5, nor do I know Lua. But I can program, and I'd say this is a good quick reference for people who do know how to program.
It gives you the syntax of the basic things and some explanations, which is what you need at the beginning.
Well done, I'd say :).
 
This is very good and I will be sure to use it.

Thank you very much :)
 
News of the day:
* The Lua introduction for confirmed developers is complete (aside, probably, of a paragraph on coroutines I forgot).
* A new, beautiful, Map and terrain article.
* A small Civ5 API FAQ that only deals with the Hungarian notation for now (may seem trivial for many of us but it bothers some beginners).
* The skeleton of a Debugging article. Since I rarely handle XML stuff, any help or advice is welcome.
 
DonQuiche said:
Since I rarely handle XML stuff, any help or advice is welcome.
Click to expand...

Some notes I made a long time ago from posts on the 2k forums with S Seckman

Code: 
<GameData>
	<!-- Create a table -->
	<Table name="NewTable">
		<!-- Auto-increment ID (primary key) -->
		<Column name="ID" type="integer" primarykey="true" autoincrement="true"/>
		<!-- Unique text key -->
		<Column name="Type" type="text" unique="true"/>
		<!-- Non-unique text field, no default value -->
		<Column name="Description" type="text"/>
		<!-- Non-unique integer field, default value of 2 -->
		<Column name="Range" type="integer" default="2"/>
		<!-- Non-unique boolean field, default value of false -->
		<Column name="Upgrade" type="boolean" default="false"/>
		<!-- Non-unique reference to the Units table, the value must be a valid Type in the Units table (ie a foreign key) -->
		<Column name="UnitType" type="text" reference="Units(Type)" default="NULL"/>
	</Table>

	<!-- Create an index on the table -->
	<Index name="NewTable_TypeIndex" table="NewTable">
		<Column name="Type"/>
		<Column name="Range"/>
	</Index>

	<!-- For the new table ... ->
	<NewTable>
		<!-- Add a row (SQL insert) -->
		<!-- Note: If this violates database integrity, the entire XML file is discarded -->
		<Row>
			<ID>0</ID>  <!-- Should only ever be given for the first row -->
			<Type>NEW_WARRIOR</Type>
			<Description>Something or other informative</Description>
			<Range>4</Range>
			<Upgrade>true</Upgrade>
			<UnitType>UNIT_WARRIOR</UnitType>
		</Row>

		<!-- Replace a row (SQL insert or replace) -->
		<Replace>
			<Type>NEW_WARRIOR</Type>
			<Description>Something or other informative</Description>
			<Range>3</Range>
			<Upgrade>true</Upgrade>
			<UnitType>UNIT_WARRIOR</UnitType>
		</replace>

		<!-- Update a row -->
		<Update>
			<Where Type="NEW_WARRIOR"/>
			<Set Range="5"/>
		</Update>
		<Update>
			<Where Type="NEW_WARRIOR" Range="2"/>  <!-- Implied AND -->
			<Set Unique="1"/>  <!-- Booleans want 0 or 1, not false or true -->
		</Update>
		<Update>
			<Where Type="NEW_WARRIOR"/>
			<Set>
				<Description>Some text to describe what it is</Description>
				<Range>3</Range>
			</Set>
		</Update>

		<!-- THIS IS NOT POSSIBLE, need to use SQL instead -->
		<Update>
			<Set Range="Range + 1"/>  <!-- Failed attempt to try to add one to all ranges -->
		</Update>

		<Delete	/>  <!-- Delete everything! -->
		<Delete	Type="NEW_WARRIOR"/>
		<Delete	Type="NEW_WARRIOR" Range="2"/> <!-- Implied AND -->
	</NewTable>

	<!-- Remove all rows in other tables that refer (ie have a foreign key) to missing Type values in NewTable -->
	<DeleteMissingReferences table="NewTable" column="Type"/>
</GameData>

Feel free to do with it as you will :)

W
 
Thank you Whoward but this is not really suited to my problem: I do know (most of) the XML syntax (and SQL of course), I even wrote a XML-SQL cheatsheet on the wiki. :)
(not very good admittedly - and the current poor syntax coloring does not help)

The problem is rather that since I rarely wrote XML files, I never encountered any bug and have absolutely no experience in debugging those kind of problems, which is obviously troublesome since I plan to write an article on debugging. I once tried to look at one of the logs for a third-party mod by curiosity, but the log was empty while I knew thanks to IGE's output that this mod had references problems.
 
You must log in or register to reply here.

Similar threads

FlammieJerynZ
[BNW] How to diagnose Random Crashes because .lua format in a Custom Mod or Modpack?
Replies
2
Views
242
ZheBerg
Z
4
Is the DLL source code for the latest (October 2014, version 1.0.3.276) patch available?
Replies
11
Views
333
whoward69
whoward69
C
Use the <update> or <replace> tag on dummy buildings for custom traits.
Replies
4
Views
229
CyanCloud
C
J
Firetuner/lua log has changed the way it outputs error messages?
Replies
2
Views
386
whoward69
whoward69
Chrisy15
Trade Route Bug - Disappearing Trade Units and Self-Generating Trade Routes
Replies
0
Views
95
Chrisy15
Chrisy15
Top Bottom