1. We have added a Gift Upgrades feature that allows you to gift an account upgrade to another member, just in time for the holiday season. You can see the gift option when going to the Account Upgrades screen, or on any user profile screen.
    Dismiss Notice

[Wiki] New Lua and UI Reference! Beta version

Discussion in 'Civ5 - Creation & Customization' started by DonQuiche, Sep 19, 2012.

  1. DonQuiche

    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.
     
  2. DonQuiche

    DonQuiche Emperor

    Joined:
    May 23, 2011
    Messages:
    1,122
    Reserved.
     
  3. Gedemon

    Gedemon Modder Super Moderator

    Joined:
    Oct 4, 2004
    Messages:
    9,628
    Location:
    France
    thank you for this :goodjob:
     
  4. The_J

    The_J Say No 2 Net Validations Retired Moderator Supporter

    Joined:
    Oct 22, 2008
    Messages:
    32,825
    Location:
    DE/NL/FR
    Looks great :yup: :thumbsup:.
     
  5. DonQuiche

    DonQuiche Emperor

    Joined:
    May 23, 2011
    Messages:
    1,122
    Erf, I just noticed I posted this in the wrong section. :p
    Could an admin move it to the parent section please?
     
  6. Gedemon

    Gedemon Modder Super Moderator

    Joined:
    Oct 4, 2004
    Messages:
    9,628
    Location:
    France
    ok, moved.
     
  7. DonQuiche

    DonQuiche Emperor

    Joined:
    May 23, 2011
    Messages:
    1,122
    Thank you Gedemon. :)
     
  8. The_J

    The_J Say No 2 Net Validations Retired Moderator Supporter

    Joined:
    Oct 22, 2008
    Messages:
    32,825
    Location:
    DE/NL/FR
    Oh well, I thought it fit well in the reference section, because at the end it's somehow a reference (or a link to a reference).
     
  9. DonQuiche

    DonQuiche Emperor

    Joined:
    May 23, 2011
    Messages:
    1,122
    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.
     
  10. Pouakai

    Pouakai It belongs in a museum. Moderator

    Joined:
    Jun 16, 2010
    Messages:
    7,158
    Location:
    Aotearoa
    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
     
  11. DonQuiche

    DonQuiche Emperor

    Joined:
    May 23, 2011
    Messages:
    1,122
    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.
     
  12. DonQuiche

    DonQuiche Emperor

    Joined:
    May 23, 2011
    Messages:
    1,122
    The bot uploaded the last page 30 minutes ago. Enjoy!
     
  13. Pazyryk

    Pazyryk Deity

    Joined:
    Jun 13, 2008
    Messages:
    3,584
    Fabulous! Thanks so much.
     
  14. DonQuiche

    DonQuiche Emperor

    Joined:
    May 23, 2011
    Messages:
    1,122
  15. The_J

    The_J Say No 2 Net Validations Retired Moderator Supporter

    Joined:
    Oct 22, 2008
    Messages:
    32,825
    Location:
    DE/NL/FR
    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 :).
     
  16. Putmalk

    Putmalk Deity

    Joined:
    Sep 26, 2010
    Messages:
    2,623
    Location:
    New York
    This is very good and I will be sure to use it.

    Thank you very much :)
     
  17. DonQuiche

    DonQuiche Emperor

    Joined:
    May 23, 2011
    Messages:
    1,122
    Thank you for your reviews. :)
    Syntax coloring will now be missing on the pages I will modify. It will be back soon.
     
  18. DonQuiche

    DonQuiche Emperor

    Joined:
    May 23, 2011
    Messages:
    1,122
    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.
     
  19. whoward69

    whoward69 DLL Minion

    Joined:
    May 30, 2011
    Messages:
    8,517
    Location:
    Near Portsmouth, UK
    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
     
  20. DonQuiche

    DonQuiche Emperor

    Joined:
    May 23, 2011
    Messages:
    1,122
    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.
     

Share This Page