SP Lua utilities

Can you help improve your favourite game? Hardcore C mages, talented artists, and players with any level of experience are welcome!
Post Reply
nef
Elite
Posts: 324
Joined: Mon Jun 25, 2018 5:01 pm

SP Lua utilities

Post by nef »

I have here a couple of Lua scripts that were, in part, inspired by Ignatus`s console scripts.

These can be run from either the client Lua console OR from a server command.

In both cases there are two output methods and either or both can be used. (See the function report at the beginning of each file.)

CLIENT CONSOLE:
  • The file can be placed more or less anywhere. The "recently used" list provides fast access.
    The log.normal (etc.) output will be written to the console so you can see it immediately.
    The chat.message output will be written to the chat log.
    I have had some occasions when use of the console has caused the client to freeze so if this becomes a problem you will have to rely on the alternative.
SERVER COMMAND:
  • The file is best placed directly under "data" or in the 'MODPACK' alternative (.freeciv/2.6).
    The log.normal (etc.) output will be written to the chat log so you can see it immediately.
    The notify.event output will be written according to client options specified for the 'EVENT'. As supplied, the files use E.BROADCAST but any can be used. Common alternatives would be SCRIPT or CHAT. Define the output destination(s) for the event used in the client game -> options -> message. NOTE that output to the message log will have HOTLINKS TO THE TILE (and city).
Both files can be renamed but the extension must be .lua.

At the moment they are NOT suitable for MP (& LT) use but if a tolua patch by Ignatus is implemented then they could be modified for client console use.
nef
Elite
Posts: 324
Joined: Mon Jun 25, 2018 5:01 pm

Re: SP Lua utilities

Post by nef »

The utility that I use the most is used to manage the free upkeep of units under despotism when using the Civ I style upkeep rules as described in this post (and this one). The printed ouput will show each city and whether it is over or under the budget (and by how much) and will look something like this

Code: Select all

/lua: Nett city upkeep costs
/lua:   1 New York
/lua:   1 Grenoble
/lua:   0 Marseille
/lua:   0 Lyon
/lua:   0 Nice*
/lua:   0 Lille
/lua:  -1 Paris
/lua:  -1 Nantes
/lua:  -1 Toulouse
/lua:  -1 Mediolanum
/lua:  -1 Toulon
ukd.txt
(1.28 KiB) Downloaded 291 times
Note that the code is expressly for Civ I style upkeep (only under despotism). Modifications to the code would make it useful for other rulesets - especially civ2civ3 where food upkeep is NOT self regulating. A pending change for fc 3.x will allow the code to be adaptive to the ruleset being used. At the moment there appears to be no direct method to determine the player`s current goverment so some assumptions need to be made for each particular version of the code you may produce. (Hacks are possible if ever a demand eventuates.)
Last edited by nef on Mon Dec 06, 2021 8:43 pm, edited 1 time in total.
nef
Elite
Posts: 324
Joined: Mon Jun 25, 2018 5:01 pm

Re: SP Lua utilities

Post by nef »

This next utility is quite general and can be used under any circumstances that I know of. As everyone knows, unhomed units are quite valuable especially in the early parts of the game. This utility can be used to keep track of them. Not only will it tell you if you still have them but hotlinks can be used to find them.
unh.txt
(425 Bytes) Downloaded 298 times
nef
Elite
Posts: 324
Joined: Mon Jun 25, 2018 5:01 pm

Re: SP Lua utilities

Post by nef »

An oversight in the first post: popups also have hotlinks to tiles (and cities), but there are some downsides: you only get one shot, and other popups typically will obscure the tile.
nef
Elite
Posts: 324
Joined: Mon Jun 25, 2018 5:01 pm

Re: SP Lua utilities

Post by nef »

The discussion over featured text has led to a number of developments in my SP utilities.

First you may recall that I was preparing three functions for use by Lua scribes, two of which I published. Some changes have accrued since then:

The link function has been split into two due to the next change.

This pair will now provide default text. This is the text that is generated by the event filtered hard code messaging system. (For cities and units - I have no idea what would happen with tiles.) It is for this reason that the function was split into two since you need to choose a different type of link if you expect the unit or city to be dead by the time the user gets to see the message.

I have actually provided a third form, which is used to create a 'short form' bbcode sequence. This form is prepared by the chat tool kbd/mouse shortcut, and has the benefit of providing a unique identifier (notably for units).

Also, I have provided the ability to obtain the default text so that the scribe can prepare complex messages.

At this point, I had a dilemma. The support code was growing rapidly, and I was reluctant to include this in EVERY utility, so I changed tack and will now provide individual support modules for different classes of SP utilities.


I have a number of utilities that I have classified into four types:
  1. Utilities that need no support. Currently, techtrade is the only one in this class and is UNCHANGED. Technically it could use bold for the heading (making it type 2) but I leave that as an exercise, which I recommend if you plan to write your own utilities using any of the materials I am providing.
  2. 'Basic' direct script utilities that require no user input and are run by simply loading the script. This class includes ukd, unh, and a new one - pollution. In the next post I will publish replacements for ukd and unh together with pollution and the two prerequisite modules.
  3. 'Extended' utilities that need user input typically userdata object (Tile, Unit, or City), plus various options. This class of utility needs to be loaded before it can be used. This step is similar to loading the prerequisites in (2) above but requires more advanced support modules - a set which can also be used for the (2) class utilities. To actually run the utility one needs to enter a function call using /lua cmd .... in the server or directly in the client command line. The userdata object (when used) can be prepared by any Lua expression such as find.unit(<id>), but for convenience, it is also possible to use a string that has featured text prepared by the kbd/mouse shortcut. So for example, if one prepared a chat command line /lua cmd home(' ') and then moved the cursor to somewhere in the string followed by indexing an object with <ctrl><alt><RMC> (City) or <ctrl><shift><alt><RMC> (Unit) (and then enter), the utility will be activated with the object and report accordingly. Note that these chat tool shortcuts will ONLY place the text into the chat line, so to use this in the client you then need to cut and paste the text. For details on the kbd/mouse shortcut see Help -> Chatline (or Help -> Controls).
  4. 'Continuity' utilities that require tolua features found only in the server. Typically these are:
    1. Callbacks. These utilities will do nothing if used in the client.
    2. Tables. To use these reliably across save/restore the tables need to be saved into the 'vars' script. To do this you will need to use the replacement version of _freeciv_state_dump. For INEXPLICABLE reasons the client offers no facility to save and restore data. These utilities can be used in the client but it is not recommended because of the lack of continuity across save/restore. This is an especially acute problem considering the GTK client (on windows) has a habit of occasionally dropping into a processor loop after using the console - requiring a quit-idle restart.
    3. tolua tables not available in the client. Currently, there is one utility that uses edit.
Edit minor typo for techtrade comments
Edit: more typos (all renumbering type 1 to type 2)
Last edited by nef on Tue Feb 28, 2023 7:41 am, edited 2 times in total.
nef
Elite
Posts: 324
Joined: Mon Jun 25, 2018 5:01 pm

Re: SP Lua utilities

Post by nef »

There are two modules required for type 2 utilities. These are:
  1. FEATURED_TEXT.
    This module contains the functions used to prepare featured text and includes:
    1. bbcode which can be used for the simple 'buis' formatting (bold, underline, italic, strike)
    2. color to provide colored text and/or colored background
    3. link, link_tile, link_quick to provide a hot link to a userdata object (Tile, Unit, or City).
    4. ftext to provide the default text used by link and link_tile
      featured.txt
      (3.32 KiB) Downloaded 189 times
  2. SUPPORT_basic.
    Two additional support functions:
    1. user - provides the userdata Player for the human player
    2. colored_link. In the case of City and Unit I found the colored text hard to read if the font was small, so I experimented with a darkened background. The color for tile (red) seems to be OK so I left that as is. Feel free to experiment (and please report if you do).
    3. background. A callable table providing the background codes used by colored_link.
      basic.txt
      (1.99 KiB) Downloaded 196 times
Both of these modules must be loaded before using any type 1 utility. This can be done by including them (first) in the utility file, or in the case of the server, by including them in an autoscript (script.lua or default.lua). INEXPLICABLY the client does NOT HAVE an autoscript facility (that I know of), so this is not an option for the client console. For both you also have the option of explicitly loading them before using any of the utilities.

Make sure you use the extension .lua for any files you use.


The utilities:
  1. Revised version of unh.
    unh.txt
    (1.42 KiB) Downloaded 201 times
  2. Revised version of ukd.
    ukd.txt
    (2.22 KiB) Downloaded 184 times
  3. pollution. When using trident I found finding polluted tiles in cluttered terrain not so easy, so I thought: well I have this computer that can do it for me.
    pollution.txt
    (1.43 KiB) Downloaded 197 times
Next week: type 3.
nef
Elite
Posts: 324
Joined: Mon Jun 25, 2018 5:01 pm

Re: SP Lua utilities

Post by nef »

3. Extended. Currently just two utilities in this class:
  1. home.
    This utility can be used for two purposes:
    1. When provided with a unit, it will identify the home city.
    2. When provided with a city, it will list all owned units.
      The list will provide featured text 'hot links' to those units not in the city.
    In both cases the argument can be userdata or featured text.
    home.txt
    (2.79 KiB) Downloaded 197 times
  2. nearest.
    When disbanding a city, the settler, and all owned units not in a city are assigned to the nearest city, which could easily result in an overload causing mass casualties. If there are multiple cities that are all the same nearest distance then the server chooses one arbitrarily. This utility can make it easier to inspect all such candidates so you can assess the potential carnage. In the file you can see that there are now two reporting options. The second allows you to use an E filter with a pop up.
    nearest.txt
    (2.88 KiB) Downloaded 201 times
To make these work you will need the following support modules:
  1. FEATURED_TEXT.
    As previous.
  2. PARSER. Contains a general purpose parser for featured text bbcode sequences
    parser.txt
    (3.65 KiB) Downloaded 183 times
  3. SUPPORT_extended.
    Similar to SUPPORT_basic, but provides a simple semantic analyser for the featured text
    extended.txt
    (3.35 KiB) Downloaded 193 times
To run these from the server I recommend you include what you need in an autoscript (script.lua or default.lua).
For the client console you could either load all the support code as one (or more) separate file(s), or package them all together in each utility.

Note that all modules have been coded to allow for arbitrary load order (provided you actually load them all before actually using a utility) and for multiple loads. Also, SUPPORT_extended includes SUPPORT_basic.

EDIT: The featured text created by chat tools uses double quotes(") for arguments. To prepare a STRING for use in Lua one should then use an alternative. Single quotes(') can be used for Units and Tiles but you may run into a problem with cities. It appears to be the case that many city names in fc actually contain a SINGLE single quote in the name instead of an apostrophe (`). So for these I recommend a long string form. The simplest of these is [[ ....]], but this too can run into problems. The featured text uses bbcode syntax which is to use single brackets ([ ...]). The problem is that if both terminations are contiguous, the Lua parser gets it 'wrong'. One can avoid this problem by making sure there is white space after the bbcode, but IMO, it is easier to use another variant such as [=[.. ]=], especially if one is using a clipboard manager.
nef
Elite
Posts: 324
Joined: Mon Jun 25, 2018 5:01 pm

Re: SP Lua utilities

Post by nef »

Type 4 utilities that use tables require additional support:
continuity.txt
(6.09 KiB) Downloaded 166 times
This support module could be loaded manually, but since type 4 utilities should only be run in the server the recommendation is to place this module in an autoscript. If this is done no other support modules are required (in the autoscript), but there will be no harm if they are there. Note that for continuity across save/restore the replacement version of _freeciv_state_dump is required and therefore should also be loaded into an autoscript. I am not aware of any ticket to include this version in any distro so you will need to load both these modules for the foreseeable future.
nef
Elite
Posts: 324
Joined: Mon Jun 25, 2018 5:01 pm

Re: SP Lua utilities

Post by nef »

STOLEN.

The first type 4 utility I have for you is 'stolen'.

Civ I keeps TWO lists of cities that have had a tech stolen by a diplomat.

Those that involve the human player as victim (and perpetrator?)

Those that involve all players.

The reason for the first list is that these are the only cities that the human player can be aware of the 'stolen' status, and so Civ I will only consult this list when the human player attempts to steal a tech (which means that the human can actually steal again even if an AI has already done so). The AI players are, of course, omniscient and they themselves will only consult the second list.

fc only keeps the second list, so the human player in fc is at a severe disadvantage, made even more extreme by 'diplomat' battles (which are not present in Civ I). One can expend, maybe half a dozen, or more, diplomats only to finally discover that an AI has already stolen from a particular city.

This utility keeps its own list so that you, as the human player, can inspect this list creating a completely level playing field. Now some might say this is going too far, but personally I think forcing you to remember the cities you have stolen from is a gotcha feature that is entirely gratuitous. If you really want it to work the way Civ I does it then it would be possible to make minor changes to the utility, but I have no plans to do so myself.



See the comments at the beginning of the file for details on use, in particular, the arguments. Note that the manual override features should never be needed in general use.
Attachments
stolen.txt
(5.83 KiB) Downloaded 184 times
Post Reply