Compatibility-breaking changes between 1.14 and 1.15/1.16

The place to post your WML questions and answers.

Moderator: Forum Moderators

Forum rules
  • Please use [code] BBCode tags in your posts for embedding WML snippets.
  • To keep your code readable so that others can easily help you, make sure to indent it following our conventions.
User avatar
Development Team
Battle for Wesnoth
Location: Wesnoth.org
Contact:

Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by Development Team »

This lists removed WML functionality and helpful hints for avoiding pitfalls.

A similar thread for changes before 1.14 can be found here.

General / promoted changes (coarse-grained):
  • Deprecated macros have been removed, no further comment on that here.
  • The new [modify_unit_type] tag is introduced, to replace the need for [advancefrom]. It has the big advantage, that it only applies to the [era], [campaign] or [modification] in which it is used. To name a good use case, if an [era] wanted to add an UMC level 3 advancement to a mainline unit, it is no longer needed to have a dummy copy of the mainline level 1 & 2 units. [modify_unit_type] will add the advancement only when the [era] is active! Please don't use [advancefrom] anymore.
  • Top level tags of add-ons, which are not involved with the currently active add-ons, are deactivated. That means in particular, [units] and [trait]s are not relevant if they are defined in an add-on which does not provide one of the currently active [campaign], [scenario], [era], [multiplayer], [modification] or [resource].
  • Campaigns now have backgrounds in the menu, the key [campaign]background= should be set.
  • [terrain_mask] now requires an x,y key. This is hard to spot, as it will fail only when this tag is used during the game.
WML (fine-grained section):
  • Overlay & trait changes:
    • [unit]overlay= cannot be changed directly anymore. Overlays are now [effects] which are part of [object]s or [trait]s. Any code which changes the [unit]overlay= key directly needs to be changed.
    • [unit]overlay= is still supported during unit creation, but not anymore afterwards. Also, this is now deprecated and best changed too.
    • {TRAIT_LOYAL} now adds automatically an overlay.
    • {TRAIT_LOYAL OVERLAY="misc/blank-hex.png~O(0)" } works around it.
    • {IS_LOYAL} is completely redundant, as the trait already adds the overlay
    • {IS_HERO} and {TRAIT_LOYAL} should be replaced by {TRAIT_LOYAL_HERO} for the correct overlay
    • {IS_HERO} without loyal trait (untypical) should use instead {TRAIT_LOYAL_HERO_NOSLOT}
    • [unit_overlay] & [remove_unit_overlay] work by adding [object]s to a unit. [remove_unit_overlay] will add an additional object on top which negates the effect of the previous one. A better method is to use instead the [object] & [remove_object] or [trait] & [remove_trait] tags.
    • {MAKE_LOYAL_HERO …} is intended to replace {MAKE_HERO …}. It has the side-effect, that the unit will have loyal as last trait.
    • {MAKE_LOYAL_NORMAL …} can replace {UNMAKE_HERO …}, if the code was adjusted to use the new loyal trait macros.
    • In addition 2 more macros were added; {MAKE_NONLOYAL …}, which removes the loyal trait, and {MAKE_LOYAL_LEADER …}, which removes the loyal trait too and makes the unit a leader instead.
  • Loading maps:
    • Instead of map_data=, maps can now be loaded with map_file=. It has the advantage that maps are loaded when they are needed, not beforehand. This was already added during 1.14.
    • The maps/ directory is now part of [binary_path]. [scenario]map_file= can load them without mentioning the full path. Due to that, please also make sure that the file names are unique among other add-ons.
      Examples:
      map_data="{~add-ons/Kromire/maps/02_Devlings.map}" # old way, using the preprocessor
      map_file=~add-ons/Kromire/maps/02_Devlings.map # new way
      map_file=02_Devlings.map # possible if using [binary_path]
      map_file=01_Start.map # WILL cause trouble due to its common name (!!)
  • New tag [special_note]
  • Special notes are now collated from all of the unit and unit_type's [special_note] tags. Notes specific to traits are now part of the trait macros instead of needing to be appended to the description; similarly notes for weapon specials are part of the weapon special macros.
    • Old way (deprecated): description="…"+{SPECIAL_NOTES}+{SPECIAL_NOTES_AMBUSH}
    • New way: any unit using {ABILITY_AMBUSH} will get the note automatically. Don't use {SPECIAL_NOTES} at all.
  • The method of using [campaign]extra_defines= to modify some advancements works now differently. Instead, add the macro directly in [campaign], not as an value to extra_defines. It uses internally [modify_unit_type] instead of [advancefrom].
  • variation_id is now required when defining a [variation].
Lua:
  • A comprehensive list of updated function names can be found here.
AI:
  • The standard AI got some new candidate actions (CAs) which were part of the experimental AI, like retreating injured units or better poison spreading.
    • In some UMC scenarios this may be unwanted, in particular the ones where the AI should be dumb and not retreat. In these cases, the retreating CA can be removed. One way to accomplish this is to use [side][ai]{MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop retreat_injured} (2 being the side number, careful when copy-pasting). Otherwise, if you want to revert all AI changes, the previous default AI is still available with [ai]ai_algorithm=ai_default_rca_1_14
    • The most differing feature of the experimental ai, the smarter recruiting, has not been merged into the default AI. When writing new scenarios, consider using it, i.e. with [side][ai]ai_algorithm=experimental_ai.
  • FormulaAI is deprecated. If you are still using it for AI behaviour, you should switch to using Lua candidate actions.
  • The return values of ai_helper.get_closest_enemy() and ai_helper.find_best_move() were changed so that they are consistent with how other Lua functions return values. This may break backward compatibility in some cases.
Units:
  • New units have been added, in particular for the dunefolk, the naga, woses and monsters.
    -> The id Dune Piercer is no longer valid
    -> The id Dune Skirmisher belonged previously to a level 2 unit, now to a level 1 one.
    -> The id Dune Warmaster belonged previously to the level 4 unit, now to a level 3 one with leadership.
    -> To find the new units ids, check the unit tree
  • A palette of animal units were added. The idea is to have for every surrounding a handful of fitting units. View the thread for inspirations. New are:
    crocodile, seahorse, cave bear, roc, jinn, wyverns, frost stoat, icemonax, ants, boars, scarab, a new scorpion, an upgrade to the fire guardian and a full race of horses.
  • A variation of the Giant Scorpion has been added, having the known resistances. The normal Giant Scorpion got completely new resistances.
  • More zombie variations exist now, new are:
    falcon, rat, boar, scorpion, spider, serpent, horse and beast_rider
  • Wose shaman, wose sapling, ant were promoted to core. If you used them, switch to the ones from core.
  • Some mounted units have now a defense cap on not only forests, but also mushroom terrain.
    To give a unit a defense cap, prefix its terrain defense value with a minus sign.
    Consider adding defense caps to your units.
Abilities & weapon specials:
  • Weaker ability regenerates +4 added
  • New ability burrow (hides units in desert and forests, but only after resting for 1 turn)
  • New ability / weapon special diversion (like backstab, but reduces chance to be hit by 20 percentage points)
  • New weapon special deflect (lowers chance to be hit by attacks when defending)
  • New weapon specials absorb (reduces or increases damage points, amount can be set)
Terrains:
  • Mushroom terrain change: ^Uf* is deprecated, two replacements exist:
    -> ^Tf* has the same visuals, but it takes now the base terrain into account (like forest does)
    -> Tb and Tb^Tf* have the same gameplay stats instead
  • New terrains have been added:
    -> Tb — Mushrooms are now not only available as overlay ^Tf, but also as base terrain.
    -> Uhe — Earthy variation of cave hills ⁵
    -> Cf, Kf — dwarvish outside castle: the old dwarvish castles are on the graphical side handled like cave terrain. This one is like castle terrain and supposed to have less glitches when combined with other castles. Its color is lighter. ²
    -> Cfr, Kfr — ruined outside dwarvish castle
    -> Cfa, Kfa — snowy outside dwarvish castle ⁴
    -> Cva, Kva — snowy elvish castle ⁴
    -> ^Esa — decorative stones, a snowy variant of ^Es
    -> Ias — ancient stone floor, a variation of Irs ³
    -> Xoa — ancient stone wall, a variation of Xos and Xoc ³
    -> Xof — overgrown stone wall ⁶
    -> Xot — catacombs ¹
    -> ^Edb — this already existing terrain has a new effect when placed on Xot ¹
    -> ^Efs — this already existing terrain will be displayed as candle instead of torch on Xot
    -> ^Eqf — iron fence, similar layout to the existing wooden fence
    -> ^Feta — snowy variation of the great tree ^Fet
    -> ^Feth — dead oak, similar to ^Fetd
    -> Rra — snowy cobbles, a variation or Rrc
  • Here is a reminder of terrains which have already been deprecated in earlier versions:
    -> Xol, an enlightened wall. Use Xos^Efs as replacement, with ^Efs being a torch overlay. ⁸
    -> Xuce, use Xuc instead
Others:
  • For players: a new command has been added: :droid full. It behaves like droiding in wesnoth 1.12.
  • For developers: the [side]controller= key is due to that no longer OOS-safe
  • For developers: a new command exists to modify terrain, e.g. : :terrain Gg^Efm
Screenshots of new terrains:
¹ (#4527)
² (#4645)
³ (#4938)
⁴ (#4616)
⁵ (#4970)
⁶ (#5173)
⁷ (#5789)

⁸ Affects in particular Loti, Trader, Trinity and the UMC terrain pack, see #4340
User avatar
octalot
General Code Maintainer
Posts: 777
Joined: July 17th, 2010, 7:40 pm
Location: Austria

Re: Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by octalot »

For the WML (fine-grained) section:

[modify_unit] has been optimised, which has had some unexpected side-effects.
  • [modify_unit]facing= currently does not update the UI. This is a bug which might be fixed later in the stable branch (#4978)
  • Using [modify_unit]side= on units on a recall list might not move units between recall lists. Discussion is in https://r.wesnoth.org/t54977
User avatar
Celtic_Minstrel
Developer
Posts: 2158
Joined: August 3rd, 2012, 11:26 pm
Location: Canada
Contact:

Re: Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by Celtic_Minstrel »

For the AI section:
  • FormulaAI is deprecated. If you are still using it for AI behaviour, you should switch to using Lua candidate actions.
  • Candidate actions can now take an optional [filter_own] to restrict the units that are used for the action.
  • You can now add candidate actions to specific units (in [unit][ai]). This is a syntax sugar for specifying a [filter_own] restricting the action to just that unit.
  • You can now add [micro_ai] tags directly in the [ai] tag. This works both in [side][ai] and [unit][ai] and is equivalent to setting up the MicroAI in a prestart event for that side or unit.
Edit: I think I somehow got confused about the purpose of this thread, sorry.
Last edited by Celtic_Minstrel on October 17th, 2021, 7:51 pm, edited 1 time in total.
Author of The Black Cross of Aleron campaign and Default++ era.
Former maintainer of Steelhive.
User avatar
Pentarctagon
Project Manager
Posts: 5496
Joined: March 22nd, 2009, 10:50 pm
Location: Earth (occasionally)

Re: Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by Pentarctagon »

Celtic_Minstrel wrote: October 16th, 2021, 3:29 pm For the AI section:
  • FormulaAI is deprecated. If you are still using it for AI behaviour, you should switch to using Lua candidate actions.
  • Candidate actions can now take an optional [filter_own] to restrict the units that are used for the action.
  • You can now add candidate actions to specific units (in [unit][ai]). This is a syntax sugar for specifying a [filter_own] restricting the action to just that unit.
  • You can now add [micro_ai] tags directly in the [ai] tag. This works both in [side][ai] and [unit][ai] and is equivalent to setting up the MicroAI in a prestart event for that side or unit.
Thanks, added.
99 little bugs in the code, 99 little bugs
take one down, patch it around
-2,147,483,648 little bugs in the code
User avatar
Celtic_Minstrel
Developer
Posts: 2158
Joined: August 3rd, 2012, 11:26 pm
Location: Canada
Contact:

Re: Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by Celtic_Minstrel »

Proof-reading:
  • "now" needs to come before the verb, not after – this affects the last two points in the first section and the third point in the WML section.
  • Wrong "its" in the map_file note and the defence cap note.
  • "A palette of animals units" – either delete "units" or remove the S on "animals".
  • "Here is a reminder of terrains…"
Additionally, the special notes section needs to be updated. I'm not sure about the best phrasing, though.
Author of The Black Cross of Aleron campaign and Default++ era.
Former maintainer of Steelhive.
User avatar
Pentarctagon
Project Manager
Posts: 5496
Joined: March 22nd, 2009, 10:50 pm
Location: Earth (occasionally)

Re: Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by Pentarctagon »

Updated the proofreading parts. For the special notes, as long as the text is correct then the wording can be improved afterwards.
99 little bugs in the code, 99 little bugs
take one down, patch it around
-2,147,483,648 little bugs in the code
User avatar
Celtic_Minstrel
Developer
Posts: 2158
Joined: August 3rd, 2012, 11:26 pm
Location: Canada
Contact:

Re: Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by Celtic_Minstrel »

Well, that's the problem. The text isn't correct. It explains an interim way of doing special notes that mostly no longer exists (though the [special_note] tag does exist still).
Author of The Black Cross of Aleron campaign and Default++ era.
Former maintainer of Steelhive.
User avatar
Pentarctagon
Project Manager
Posts: 5496
Joined: March 22nd, 2009, 10:50 pm
Location: Earth (occasionally)

Re: Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by Pentarctagon »

IIRC you were the person who implemented the new way though, right?
99 little bugs in the code, 99 little bugs
take one down, patch it around
-2,147,483,648 little bugs in the code
User avatar
Celtic_Minstrel
Developer
Posts: 2158
Joined: August 3rd, 2012, 11:26 pm
Location: Canada
Contact:

Re: Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by Celtic_Minstrel »

It was partly me and partly octalot.
Author of The Black Cross of Aleron campaign and Default++ era.
Former maintainer of Steelhive.
User avatar
Pentarctagon
Project Manager
Posts: 5496
Joined: March 22nd, 2009, 10:50 pm
Location: Earth (occasionally)

Re: Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by Pentarctagon »

Celtic_Minstrel wrote: October 18th, 2021, 5:11 am It was partly me and partly octalot.
Can you and-or octalot write a short, updated description of the changes?
99 little bugs in the code, 99 little bugs
take one down, patch it around
-2,147,483,648 little bugs in the code
mattsc
Inactive Developer
Posts: 1217
Joined: October 13th, 2010, 6:14 pm

Re: Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by mattsc »

The AI section generally looks good. There are two backward compatibility breaking changes to ai_helper functions. Should those be added? Is so:

The return values of ai_helper.get_closest_enemy() and ai_helper.find_best_move() were changed so that they are consistent with how other Lua functions return values. This may break backward compatibility in some cases.

I would change one of the bullets:

In some UMC scenarios this may be unwanted, in particular the ones where the AI should be dumb and not retreat. In these cases, the retreating CA can be removed. One way to accomplish this is to use [side][ai]{MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop retreat_injured} (2 being the side number, careful when copy-pasting). Otherwise, if you want to revert all AI changes, the previous default AI is still available with [ai]ai_algorithm=ai_default_rca_1_14

Also, I would make the current 2nd and 3rd bullets sub-bullets of the first, rather than top-level bullets.
User avatar
Pentarctagon
Project Manager
Posts: 5496
Joined: March 22nd, 2009, 10:50 pm
Location: Earth (occasionally)

Re: Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by Pentarctagon »

mattsc wrote: October 19th, 2021, 1:00 am The return values of ai_helper.get_closest_enemy() and ai_helper.find_best_move() were changed so that they are consistent with how other Lua functions return values. This may break backward compatibility in some cases.
It would be good to state how it was changed explicitly, since the reader might not be familiar with what it means in practice.
99 little bugs in the code, 99 little bugs
take one down, patch it around
-2,147,483,648 little bugs in the code
mattsc
Inactive Developer
Posts: 1217
Joined: October 13th, 2010, 6:14 pm

Re: Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by mattsc »

Sure. I hadn't added this because ai_helper is no documented on the wiki, so (most) anybody who uses it probably knows to look into the comments inside the file (which I tried to make pretty clear and explicit). But either way, how's this:

The return values of ai_helper.get_closest_enemy() and ai_helper.find_best_move() were changed so that they are consistent with how other Lua functions return values. This may break backward compatibility in some cases. ai_helper.get_closest_enemy() now returns the closest enemy first, and the closest distance second (as opposed to the other way around). ai_helper.find_best_move() now returns nil instead of {} if no move is found.
User avatar
octalot
General Code Maintainer
Posts: 777
Joined: July 17th, 2010, 7:40 pm
Location: Austria

Re: Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by octalot »

Celtic_Minstrel wrote: October 18th, 2021, 4:13 am Well, that's the problem. The text isn't correct. It explains an interim way of doing special notes that mostly no longer exists (though the [special_note] tag does exist still).
As I was asked to write this up:
  • New tag [special_note]
  • Special notes are now collated from all of the unit and unit_type's [special_note] tags. Notes specific to traits are now part of the trait macros instead of needing to be appended to the description; similarly notes for weapon specials are part of the weapon special macros.
    • Old way (deprecated): description="…"+{SPECIAL_NOTES}+{SPECIAL_NOTES_AMBUSH}
    • New way: any unit using {ABILITY_AMBUSH} will get the note automatically. Don't use {SPECIAL_NOTES} at all.
User avatar
Pentarctagon
Project Manager
Posts: 5496
Joined: March 22nd, 2009, 10:50 pm
Location: Earth (occasionally)

Re: Compatibility-breaking changes between 1.14 and 1.15/1.16

Post by Pentarctagon »

Thanks, I've updated the post.
99 little bugs in the code, 99 little bugs
take one down, patch it around
-2,147,483,648 little bugs in the code
Post Reply