Difference between revisions of "UsefulWMLFragments"

Latest revision as of 13:27, 13 September 2022

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.*

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

WML Abilities: Knockback. Charm. Bloodlust.

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

Advanced Optimisations and Hacks: If you're coding something really complex, this might come handy

@@ Line 1: / Line 1: @@
 == Useful WML Fragments ==
-''The reorganization of this page is still incomplete. Scroll down to see the contents of the old 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.
-[[WML Utilities]]: Convenient shortcuts for the most common tasks, such as variable formatting, storing/unstoring and modifying of units, and so on. Also some utility macros for more complex tasks, such as mirroring hex coordinates. Generally useful, scenario-independent little helpers.
-[[WML Scenario Tools]]: WML for shops, items, wishing wells, victory conditions and more. In short, things that you use only in specific scenarios.
-[[WML Abilities]]: Unit abilities and specials implemented in WML. Cannot currently be incorporated in the unit type definitions themselves, but must be individually included in every scenario in which they should work.
-[[WML Buildings]]: Various buildings. Not yet active.
-[[WML Templates]]: Generic campaign, scenario and unit templates.
+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 [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 ===
+*[[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.*
+==== 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 ====
+*[[WML Abilities]]: Knockback. Charm. Bloodlust.
+==== 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 ===
+*[[Advanced Optimisations and Hacks]]: If you're coding something really complex, this might come handy
+== See Also ==
+* [[ReferenceWML]]
-[[WmlTemplates]]: Campaign, scenario and unit templates, for the lazy ;)
-Currently, these are all macros (see [[PreprocessorRef]])
+[[Category: UsefulWMLFragments|*]]
-that may 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.
-[[ProgrammingMacros]]: Definitions for some low-level macros to make it easier to write program-like WML.
-[[WML Macros]]: Convenient shortcuts for the most common tasks, such as variable formatting, storing/unstoring and modifying of units, and so on.
-[[Advanced WML]]: Ways of accomplishing some unusual things with WML.
-[[WishingWell]]: Hero(es) can get boosts for traits at a wishing well.
-[[DroppableItem]]: A macro to create items that units can carry, that are left on the ground when those units die.
-[[RandomTraitUnit]]: A series of macros to create a unit with two random traits.
-[[PseudoRandom]]: A replacement for {RANDOM} in multiplayer, where {RANDOM} is buggy.
-[[MoveExistingUnit]]: A general way to move a unit from one place to another, displaying its movement.
-[[BranchOnVillageType]]: Crude hack for branching on village type.
-[[Rain effect]]: Creating an overlay of rain in a scenario.
-[[Victory Conditions]]: Macros for different kinds of victory conditions, for example victory by controlling x% of villages on the map. Also suitable for multiplayer scenarios.
-[[A Shop Like Thing]]: How to add even more RPG elements to your scenarios.
-== See Also ==
-* [[ReferenceWML]]