Missing Lua functionality for cities

What would you like to see in Freeciv? Do you have a good idea what should be improved or how?
Posts: 339
Joined: Mon Nov 06, 2017 12:05 pm
Location: St.Petersburg, Russia

Missing Lua functionality for cities

Postby Ignatus » Sun Dec 23, 2018 8:46 pm

Methods and properties of City type that are missing but should be:
  • :transfer(player, reason?) - changes the owner of the city to player, if reason (same as in city_transferred callback) is specified, triggers side effects of this cause of changing hands (i.e. "conquest"=>reduces pop); maybe add third parameter for if to post the standard messages. Returns true if the city is handed to player, false if destroyed and nil if the action is invalid.
  • :destroy(reason?)
  • :citizens_happy(level?), :citizens_content(level?), :citizens_unhappy(level?), :citizens_angry(level?) - number of citizens in such a mood, level is "base", "luxury", "effect", "nationality", "martial" or "final" (default) - according to enum citizen_feeling
  • .nationalities - gives a table {[Nation_Type] = amount_of_citizens}.
  • :specialists(spec_type?) - current number of specialists of given type.
  • :worked_tiles() - iterator by tiles currently worked. Do we need to have Lua-driven CMAs?
  • :reduce_pop(amount?,reason?), default amount=1, reasons like in city_size_change callback. Returns several values in pairs number_n, Nation_Type n for number and nationality of the citizens removed; may destroy the city.
  • :add_pop(reason?, number?, nation?, ...) - increases city population, number defaults to 1 and nationality to city owner (accepts :reduce_pop() results for easy migration)
  • :base_production(otype), :production(otype), :waste(otype), :unhappy_penalty(otype), :surplus(otype), :usage(otype) - production characteristics of given output type ("food", "shield", "trade", "gold", "luxury", "science")
  • .food_stock, :food_stock_add(amount) (can't be reduced below 0)
  • .shield_stock, :shield_stock_add(amount) (can't be reduced below 0)
  • .before_change_shields, .caravan_shields, .disbanded_shields, .last_turns_shield_surplus - some shield sources. To which one do we add by Lua? May we ever need to change them?
  • .production, .production_genus, .changed_from, .changed_from_genus - current production may be Building_Type or Unit_Type, we can rethink change within a turn. Do we need to set it or manipulate the whole worklist by Lua (at least, the client one) or let a Lua function be an item in the production list?
  • .turn_founded
  • .turn_plague - when last struck by illness
  • .turn_last_built
  • .anarchy_turns, .rapture_turns - counters before it happens, 0 if never (in C code there are accumulators). May we ever need to change them?
  • .airlift, :set_airlift(n), .airlifts_left - number of units airlifted this turn (to, from - counted according to the game settings).
  • .did_buy, .did_sell, .was_happy - flags of recent actions
  • :history()
  • :create_building(building_type), :destroy_building(building_type) - manipulate the city improvements. Do not check the ability of the player to build it but check if it can't be built due to obsoletion or wonder built status (mb need :can_create(building) to precheck); but anything can be destroyed.
  • :trade_with(another_city?), :trade_base() - components of city trade
  • :trade_routes() - iterates by cities we do have trade routes to/from. Usage:

    Code: Select all

    for city, goods, trade, direction in aCity:trade_routes() do

    direction is nil for bidirectional trade. If the city is not seen, the client scripts need some Obscure_City class for it (in fact, many things above you don't know for foreign cities)
  • :establish_trade_route_to(city, goods), :cancel_trade_route_to(city, goods?) (may add ..._from and ..._with methods for convenience) - return nil if failed
  • :potential_trade_to(city, goods) (disregarding if we have the goods)
  • :goods() - iterates by goods in the city
  • Server-only (editing actions above are also server-only of course):
    • bring_disaster(disaster) - causes a disqster to happen in the city, requirementa disregarding
    • .migration_score (needs updating sometimes when we calculate it?)
    • .illness - probability, don't understand if C field is before traderoutes effect or with it, maybe we need both. In the client, we also have some plague chance sent by the server.
    • .steal_count, :set_steal_count(n)
    • .workers_frozen - if >0, prohibits workers rearrangement. Probably should not be touched. But when we have pinned workers, we might need an automation to autopin/unpin.
    • C field adv_city includes some info stored by the advisors; what would be great to set by scripts is buildings adv_want if we can advise a building better or worse due to scripted effects.
    • :investigate_for(player) - make the player's client to pop up an investigation dialog.
  • Client-only:
    • .occupied - for foreign cities we don't know how many are inside but sometimes know if any
    • .walls - we see them, in newer version can be of several types
    • .colored, .color_index, .set_colored(bool), .set_color_index(int)
    • Some information from city investigation, currently we can only record what we see in the dialog on a napkin.

(I have left some suggestions on unit-related API here).

Posts: 1
Joined: Wed Feb 27, 2019 5:38 am
Location: NY

Re: Missing Lua functionality for cities

Postby supersmashunblocked2 » Wed Feb 27, 2019 5:54 am

Oh my goodness! Very nice info... ;) ;) ;)