Difference between revisions of "UsefulWMLFragments"

From The Battle for Wesnoth Wiki
(MAJOR CHANGE! Changed structure of page completely. Kept links but it should all make sense now.)
(46 intermediate revisions by 14 users not shown)
Line 1: Line 1:
 
== Useful WML Fragments ==
 
== Useful WML Fragments ==
  
NOTES ABOUT ADDING PAGES: Don't add new pages here. Find a category in which your code fits and add it to that page.
+
Most of the things found here are macros (see [[PreprocessorRef]]) that must be copied into a scenario file or another file included first by the campaign, and then used in the scenario (or multiplayer map). Remember that a macro cannot be used at a point before it is defined.
  
Most of the things found here are macros (see [[PreprocessorRef]]) that must be copied into a scenario file or another file included first by the campaign, and then used in the scenario (or multiplayer map). Remember that a macro cannot be used at a point before it is defined.
+
Also, when creating or using macros, please remember: Every macro must generate a WML fragment which would be syntactically balanced and correct by itself. Unbalanced macros confuse our maintenance and sanity-checking tools, creating extra work and headaches for the already-overworked WML maintainers.
  
For a step by step instruction, look here: [[HowTo: IncludeMacros]] and then here: [[HowTo: UseMacros]]
+
'''Note: some of the code here is outdated or otherwise poor. It's not advisable to blindly copy-paste code from here and expect it to work on recent Wesnoth versions or assume that the recent versions don't support a simpler and less hacky way of doing the same thing.'''
  
High level macros often require the lower level macros found in ProgrammingMacros, Utilities, and Scenario Tools.
+
Some things '''not''' to do here:
 +
* Don't add macros that duplicate things in [http://www.wesnoth.org/macro-reference.xhtml the core macro library].
 +
* Don't add macros that are trivial syntax shortcuts.
 +
* Don't add macros that generate unbalanced syntax fragments.
  
 +
Try to avoid adding pages here. It is better to find a category in which your code fits and add it to that page.
  
 
=== Logic Structure Macros ===
 
=== Logic Structure Macros ===
*[[ProgrammingMacros]]: Definitions for some low-level macros to make it easier to write program-like WML.
+
*[[WML Utilities]]: Macros to assist other macros. Overlay with Filter. Determine Opposite Coordinates. Find nearest hex(es)
*[[WML Utilities]]: Macros to assist other macros. Test Value of Variable. If Have Unit. Store Unit Attribute. Filter by Terrain. Iterate. Overlay with Filter. Determine Opposite Coordinates.  
 
  
 +
==== RPG Tools ====
 +
*[[A Shop Like Thing]]: How to add even more RPG elements to your scenarios.
 +
*[[CutsceneWML]]: Fixed MOVE_TO event (uses FIND_NEARBY from [[WML Utilities]]), move + exit to recall list, define character dialogue and a "main character", grant unlimited moves.*
 +
*[[An effect that changes icons]]: Wanted to change some attack's icon when the unit took an object, but there was no set_icon variable accepted? This enables it!
  
=== Campaign Tools ===
+
==== Music Tools ====
*[[WML Scenario Tools]]: Macros directly useful in a scenario. Modify unit. Give villages to a side. Return Unit to Recall List. Trap Unit. Change Keep Terrain. Hero die message. Item effect.
+
*[[WML Musical Moods]]: Groups the Wesnoth music (as of 1.7.x) into "moods" and defines macros for playing randomly songs from these pools and for quickly switching music.
*[[WML Dialog Tools]]: Macros useful for unit dialog/storyboarding. Character Speaker, Blank story section, Delays and Fades.
 
*[[Victory Conditions]]: Number of Villages, Amount of Gold. Suitable for multiplayer scenarios.
 
 
 
==== Map Tools ====
 
*[[A Shop Like Thing]]: How to add even more RPG elements to your scenarios.
 
*[[Rain effect]]: Creating an overlay of rain in a scenario.
 
  
 
==== Unit Tools ====
 
==== Unit Tools ====
*[[MoveExistingUnit]]: Move a unit from one place to another, displaying its movement. Move Unit 1. Move Unit 2. Move Unit 3.
+
*[[WML Abilities]]: Knockback. Charm. Bloodlust.
*[[WML Abilities]]: Knockback. Charm. Bloodlust. Abilities cannot currently be incorporated in the unit type definitions themselves, but must be included in the scenario file.
 
*[[WML Buildings]]: Generic Buildings, Light House/Dark Tower, Wishing Well #1, Wishing Well #2.
 
*[[RandomTraitUnit]]: Create a unit with two random traits. (very simple.) (updated)
 
  
 
==== Item Tools ====
 
==== Item Tools ====
*[[DroppableItem]]: Generic item that a unit can carry, and is left on the ground when the unit dies.
+
*[[DroppableItem]]: For placing items on the terrain upon death of a unit.
 
 
 
 
=== Multiplayer Tools ===
 
*[[PseudoRandom]]: A replacement for {RANDOM} in multiplayer, where {RANDOM} is buggy.
 
  
 +
==== Map Tools ====
 +
*[[FloodWML]]: Macros to create a flood of a certain terrain type spreading across the map.
  
 
=== Advanced WML ===
 
=== Advanced WML ===
*[[Advanced WML]]: Branch on Village Type. Recruit from a Ship. Point Rotation Scheme.
+
*[[Advanced Optimisations and Hacks]]: If you're coding something really complex, this might come handy
 
 
 
 
=== Templates ===
 
*[[WML Templates]]: Generic campaign, scenario and unit templates. (updated)
 
  
 
== See Also ==
 
== See Also ==
Line 50: Line 42:
  
  
[[Category: UsefulWMLFragments]]
+
[[Category: UsefulWMLFragments|*]]

Revision as of 06:35, 23 January 2021

Useful WML Fragments

Most of the things found here are macros (see PreprocessorRef) that must be copied into a scenario file or another file included first by the campaign, and then used in the scenario (or multiplayer map). Remember that a macro cannot be used at a point before it is defined.

Also, when creating or using macros, please remember: Every macro must generate a WML fragment which would be syntactically balanced and correct by itself. Unbalanced macros confuse our maintenance and sanity-checking tools, creating extra work and headaches for the already-overworked WML maintainers.

Note: some of the code here is outdated or otherwise poor. It's not advisable to blindly copy-paste code from here and expect it to work on recent Wesnoth versions or assume that the recent versions don't support a simpler and less hacky way of doing the same thing.

Some things not to do here:

  • Don't add macros that duplicate things in the core macro library.
  • Don't add macros that are trivial syntax shortcuts.
  • Don't add macros that generate unbalanced syntax fragments.

Try to avoid adding pages here. It is better to find a category in which your code fits and add it to that page.

Logic Structure Macros

  • WML Utilities: Macros to assist other macros. Overlay with Filter. Determine Opposite Coordinates. Find nearest hex(es)

RPG Tools

  • A Shop Like Thing: How to add even more RPG elements to your scenarios.
  • CutsceneWML: Fixed MOVE_TO event (uses FIND_NEARBY from WML Utilities), move + exit to recall list, define character dialogue and a "main character", grant unlimited moves.*
  • An effect that changes icons: Wanted to change some attack's icon when the unit took an object, but there was no set_icon variable accepted? This enables it!

Music Tools

  • WML Musical Moods: Groups the Wesnoth music (as of 1.7.x) into "moods" and defines macros for playing randomly songs from these pools and for quickly switching music.

Unit Tools

Item Tools

  • DroppableItem: For placing items on the terrain upon death of a unit.

Map Tools

  • FloodWML: Macros to create a flood of a certain terrain type spreading across the map.

Advanced WML

See Also