Difference between revisions of "UsefulWMLFragments"

From The Battle for Wesnoth Wiki
m (putting it to the top of the list n ithe category)
(42 intermediate revisions by 12 users not shown)
Line 1: Line 1:
{{Needs update}}
 
 
 
== Useful WML Fragments ==
 
== Useful WML Fragments ==
  
NOTES ABOUT ADDING PAGES: try not to 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. (old)
 
*[[Map Modification WML]] Tools for editing the terrain in creative ways
 
  
 
==== 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]]: Macros to drop items. Currently only macros for dropping items on unit death including a permenant item that can be picked up, and dropped, multiple times by different units.
+
*[[DroppableItem]]: For placing items on the terrain upon death of a unit.
*[[General Item WML]]
 
 
 
 
 
=== Multiplayer Tools ===
 
*[[PseudoRandom]]: A replacement for {RANDOM} in multiplayer, where {RANDOM} is buggy.
 
*[[General Multiplayer WML]]
 
  
 +
==== 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 ==

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