Controlling Lua Enhancements with Rules.txt

[Knighttime]

@Prof. Garfield I realize that when I originally spoke up in favor of this idea, it was in the context of adding new sections to Rules.txt. But in thinking through this a little bit more... I'm actually inclined to favor using a new, separate .txt file for this -- perhaps something like Rules_LST.txt. This could follow the same familiar format, of course, for consistency and ease of use.

The existing Rules.txt file already contains multiple sections and extra fields that are only supported if you're running TOTPP, sometimes a specific minimum version of TOTPP, which seems complex enough. So if you're adding entirely new sections that are only going to be recognized and supported by the Lua Scenario Template, maybe having those stored in a separate .txt file would make that relationship abundantly clear. (You wouldn't try to support additional fields/columns in existing sections, right? this would only be entirely new ones? So I don't think this would limit capabilities in any way.)

Just my two cents, I'll leave the final decision up to you.

 

[Prof. Garfield]

It doesn't matter to me whether the enhancements are in the rules.txt file or in some other file. I'll let others weigh in on what suits them better. My plan is to give each relevant section a name that begins with @LUA, so it is clear that the section deals with Lua enhancements. If the rules.txt file has the name of the section, but not all the rows, an error is generated which will print (in the console) a sample version of the section that leaves everything as a default. I'm not going to add extra fields to existing sections. I don't know if that will break anything, and I see no value worth the trouble of finding out.

 

[CurtSibling]

Making this potential Rules/Lua hybrid more user-friendly to non-programmer modders is a good aim...

 

[Prof. Garfield]

Making this potential Rules/Lua hybrid more user-friendly to non-programmer modders is a good aim...

Well, is it more user-friendly if the Lua portion of the rules are in the rules.txt file, or is it easier if they're separate? To me, it doesn't seem like it would make any difference. I'm currently building under the assumption that it will be in the regular rules.txt file, but I only have to change 1 or 2 lines of code to read from somewhere else.

 

[Knighttime]

My plan is to give each relevant section a name that begins with @LUA, so it is clear that the section deals with Lua enhancements. If the rules.txt file has the name of the section, but not all the rows, an error is generated which will print (in the console) a sample version of the section that leaves everything as a default. I'm not going to add extra fields to existing sections. I don't know if that will break anything, and I see no value worth the trouble of finding out.

I think besides ease-of-use for modders, another valid goal would be staying out of TNO's way in case he wants to add new sections to Rules.txt in the future (that would be supported directly by TOTPP). A good naming convention for new sections, like what you proposed here, would definitely help keep things clear to users and also make it pretty easy for TNO to avoid conflicts. I'd still vote for a separate file, but I think you have a good plan in place to minimize any disruptions if you do go the single-file route.

As a minor point of order I know it's quicker for people to say "Lua" in situations where what they really mean is "Lua Scenario Template". But since it's possible to use Lua in a scenario without this Template, I'd vote for using the acronym "LST" in cases where that's really what's meant. I know I'm in the very small minority (at this point) of people working in Lua without really using most of your Template, and I can certainly make the distinction when necessary, so this is mostly me being pedantic about small details (sorry). I'll be quiet now and let you carry on with your good work!

 

[JPetroski]

Well, is it more user-friendly if the Lua portion of the rules are in the rules.txt file, or is it easier if they're separate? To me, it doesn't seem like it would make any difference. I'm currently building under the assumption that it will be in the regular rules.txt file, but I only have to change 1 or 2 lines of code to read from somewhere else.

As long as it looks like the rules file (commas, flags, etc.) I really don't think it matters if it is a different file.

 

[CurtSibling]

I agree. If we want more people to adopt Lua, keeping things CIV2-familiar is key.

 

[techumseh]

I agree. If it can be edited simply, like the existing Rules file, then it makes sense. My reason is just that the Rules file is already getting pretty long, and this would make the Lua-based rules easier to find.

(edit) I really like this direction. I goes a long way towards making Lua more accessible to those of us who are programming-challenged.

 

[Prof. Garfield]

I've decided to use a separate file for the Lua Scenario Template Rules. The deciding factor is that I can have a script automatically generate the entire file. To avoid errors, the first entry in each row is the unit name, so a generic "empty" file won't really work.

 

[Prof. Garfield]

I've made some progress with the Lua Scenario Template Rules. Here's what's available now. With the most recent template, you can press CTRL+SHIFT+F4 to generate a rules_lst.txt file. If you're planning on using this for a scenario, don't start final events work just yet. The enhanced rules integration touches a lot of other files, so it won't be easy to upgrade with new features. Still, you can play around with what's available.

;
;       Lua Scenario Template Rules
;       This file is organized very similarly to the rules.txt file.
;       It is designed to provide you with some of the functionality
;       offered by Lua Events in a familiar format
;
;       Custom Combat Groups and Modifiers
; A) Unit Name: No direct effect, but if the unit name doesn't match
;       the name for the unit with the same ID, a warning is printed
;       in the console
; B) Combat Group Membership mask:     0: not in group;    1: in group
;       0000000000000001    Group 0
;       0000000000000010    Group 1
;       0000000000000100    Group 2
;       0000000000001000    Group 3
;       0000000000010000    Group 4
;       0000000000100000    Group 5
;       0000000001000000    Group 6
;       0000000010000000    Group 7
;       0000000100000000    Group 8 
;       0000001000000000    Group 9
;       0000010000000000    Group 10
;       0000100000000000    Group 11
;       0001000000000000    Group 12
;       0010000000000000    Group 13
;       0100000000000000    Group 14
;       1000000000000000    Group 15
; C) Percentage Increment:      Determines how much the modifier masks change with
;                               each increase.  25 means the increment is 25%
; D) Attack Modifier mask:      0: Can't attack group, 1-9: multiply attack power by percentage increment 
;                               when attacking that group.  That is, if the increment is 25,
;                               1: 25% power, 2: 50% power, 3: 75% power, 4: 100%, 5: 125%
;                               *: attack with normal power against group
; E) Defense Modifier mask:     0-9: multiply defender power by the percentage increment
;                               when defending against attacks from that group.
;                               That is, if the increment is 33.
;                               1: 33% of normal, 2: 66% of normal, 3: 99% normal, 4: 132% normal, etc
;                               *: defend at normal value against group
;        A                     B            C           D                  E

;        Combat Group Names
;  This section defines names for the 16 combat groups
;  in  the @LSTCOMBATGROUPS section,
;  starting with Group 0 in the first line.
;  These names will be used for some automatically generated
;  documentation.
@LSTCOMBATGROUPNAMES
Combat Group 0, ; Combat Group 0
Combat Group 1, ; Combat Group 1
Combat Group 2, ; Combat Group 2
Combat Group 3, ; Combat Group 3
Combat Group 4, ; Combat Group 4
Combat Group 5, ; Combat Group 5
Combat Group 6, ; Combat Group 6
Combat Group 7, ; Combat Group 7
Combat Group 8, ; Combat Group 8
Combat Group 9, ; Combat Group 9
Combat Group 10, ; Combat Group 10
Combat Group 11, ; Combat Group 11
Combat Group 12, ; Combat Group 12
Combat Group 13, ; Combat Group 13
Combat Group 14, ; Combat Group 14
Combat Group 15, ; Combat Group 15
;       Demotions
; A) Unit Name: No direct effect, but if the unit name doesn't match
;       the name for the unit with the same ID, a warning is printed
;       in the console
; B) Demotion Group Membership mask:     0: not in group;    1: in group
;       0000000000000001    Group 0
;       0000000000000010    Group 1
;       0000000000000100    Group 2
;       0000000000001000    Group 3
;       0000000000010000    Group 4
;       0000000000100000    Group 5
;       0000000001000000    Group 6
;       0000000010000000    Group 7
;       0000000100000000    Group 8 
;       0000001000000000    Group 9
;       0000010000000000    Group 10
;       0000100000000000    Group 11
;       0001000000000000    Group 12
;       0010000000000000    Group 13
;       0100000000000000    Group 14
;       1000000000000000    Group 15
;       
; C) Demotion Unit: If a unit is defeated, replace it with the unit 
;       corresponding id number (starting at 0).  nil means the unit is
;       not replaced upon destruction
; D) Destroy if Killed By Mask:  0: Ignore this group for demotions
;       1: If killer is in this group, destroy the unit instead of demoting it.
; E) Demotion Settings:
;       00000001    Vet Status Change: 0: Keep current vet status when demoted
;                                      1: Give vet status upon demotion   
;                                      2: Remove vet status upon demotion
;       00000010    Demote only if veteran: 0: Demote regardless of vet status
;                                      1: Demote only if veteran
;       0000ab00    Damage to replacing unit: Replacing unit should be given
;                                      ab damage upon creation, i.e. 00002300
;                                      would create a unit with 23 damage already
;       11110000    Reserved (no effect)
;          A                   B             C            D               E
@LSTDEMOTION
;       Promotions
; A) Unit Name: No direct effect, but if the unit name doesn't match
;       the name for the unit with the same ID, a warning is printed
;       in the console
; B) Veteran Status Chance: Percent chance for a unit to be given veteran status
; C) Promotion Group Membership mask:     0: not in group;    1: in group
;       0000000000000001    Group 0
;       0000000000000010    Group 1
;       0000000000000100    Group 2
;       0000000000001000    Group 3
;       0000000000010000    Group 4
;       0000000000100000    Group 5
;       0000000001000000    Group 6
;       0000000010000000    Group 7
;       0000000100000000    Group 8 
;       0000001000000000    Group 9
;       0000010000000000    Group 10
;       0000100000000000    Group 11
;       0001000000000000    Group 12
;       0010000000000000    Group 13
;       0100000000000000    Group 14
;       1000000000000000    Group 15
; D) Promotion Unit: If a unit is victorious in combat, it may be promoted to the unit with
;       this id number (starting at 0). nil means the unit can't be promoted
; E) Promotion Chance: Percent chance for a unit to be promoted to the new unit.
; F) Do Not Promote For Kill By Mask:  0: ignore this group for promotions
;       1: If defeated unit is in this group, do not promote the unit
; G) Promotion Flags:
;       00000001    Non Vet Upgrade: 1: unit can upgrade if not vet 0: must be vet to upgrade
;       00000010    Change Vet Status: 0:unit retains current vet status 1: unit loses vet status
;                        if it has it 2: unit gains vet status if it doesn't have it
;       00000100    Heal Unit: 0: Unit retains existing damage upon upgrade 1: unit fully healed
;       00001000    Preserve HP: 0: Unit keeps existing damage 1: Unit keeps existing hitpoints
;                   e.g. 20 hp unit with 7 hp (13 damage) left upgraded to 30 hp unit type:
;                   0: new hp is 17 (13 damage), 1: new hp is 7 (23 damage)
;       00010000    Spend Move: 0-9: spend this many movement points upon upgrade *: spend all movement
;       00100000    Not assigned
;       01000000    Not assigned
;       10000000    Not Assigned
; 
;          A             B            C             D      E            F               G
@LSTPROMOTION
;       Production Veteran Status
; A) Unit Name: No direct effect, but if the unit name doesn't match
;       the name for the unit with the same ID, a warning is printed
;       in the console
; B) Base Veteran Status Chance Increment: Percent chance the unit produced will be
;       veteran, before applying improvements and wonders
; C) Standard Improvement Veteran Chance Increment: Percent chance that a barracks,
;       port facility, or airport will produce a veteran unit
;       (add this with the base chance)
; D) Wonder Veteran Chance Increment: Percent chance that a unit produced by a civ
;       owning Sun Tzu or Lighthouse will be veteran
;       (add this with previous chances for total chance)
; E) First Supplemental Improvement: ID of improvement or wonder that will add
;       a chance for a produced unit to be veteran
;       (Pyramids is ID 40 in this system, Hanging Gardens 41 and so on)
;       nil means don't use this improvement
; F) First Supplemental Veteran Chance Increment: If the supplemental improvement is in
;       the city, or the wonder is owned and active by the tribe, then
;       this is the percent chance that the produced unit will be veteran
;       (add with all previous chances for the total chance)
; G) Second Supplemental Improvement: ID of improvement or wonder that will add
;       a chance for a produced unit to be veteran
;       (Pyramids is ID 40 in this system, Hanging Gardens 41 and so on)
;       nil means don't use this improvement
; H) Second Supplemental Veteran Chance Increment: If the supplemental improvement is in
;       the city, or the wonder is owned and active by the tribe, then
;       this is the percent chance that the produced unit will be veteran
;       (add with all previous chances for the total chance)
; I) Tribe Bonus Mask:
;       0-9: Multiply value by 10%, and add that chance to the probability a unit
;       will be produced veteran by the associated tribe/government
;       *: 100% chance the tribe/govt will produce a veteran unit
;       0000000000000001    Tribe 0 (Barbarians)
;       0000000000000010    Tribe 1
;       0000000000000100    Tribe 2
;       0000000000001000    Tribe 3
;       0000000000010000    Tribe 4
;       0000000000100000    Tribe 5
;       0000000001000000    Tribe 6
;       0000000010000000    Tribe 7
;       0000000100000000    Anarchy 
;       0000001000000000    Despotism
;       0000010000000000    Monarchy
;       0000100000000000    Communism
;       0001000000000000    Fundamentalism
;       0010000000000000    Republic
;       0100000000000000    Democracy
;       1000000000000000    Unassigned Bit
; 
;        A               B      C      D      E      F      G      H             I 
@LSTPRODUCTIONVETERANSTATUS