BinaryPathWML - Revision history

Bssarkar: /* the toplevel [binary_path] tag */ typofix: it -> in

2026-06-18T03:33:47Z

the toplevel [binary_path] tag: typofix: it -> in

← Older revision		Revision as of 03:33, 18 June 2026
Line 3:		Line 3:

	This tag is used to recognize more than one directory as containing images, music, and sound. It only has one key:		This tag is used to recognize more than one directory as containing images, music, and sound. It only has one key:
	* '''path''': a directory. When an image is not found it the normal ''images'' directory, it will be looked for in '''''path'''/images''. Similarly,		* '''path''': a directory. When an image is not found in the normal ''images'' directory, it will be looked for in '''''path'''/images''. Similarly,
	** music will be looked for in '''''path'''/music'', and		** music will be looked for in '''''path'''/music'', and
	** sound in '''''path'''/sound''.		** sound in '''''path'''/sound''.

Celtic Minstrel: /* Resolving paths against the binary path */ New section

2023-07-23T14:35:36Z

Resolving paths against the binary path: New section

← Older revision		Revision as of 14:35, 23 July 2023
Line 11:		Line 11:

	[binary_path] should only be used where necessary. For example a multiplayer era should have its [binary_path] inside an #ifdef MULTIPLAYER instead of outside it in order to avoid possible clashes with single-player content.		[binary_path] should only be used where necessary. For example a multiplayer era should have its [binary_path] inside an #ifdef MULTIPLAYER instead of outside it in order to avoid possible clashes with single-player content.

			== Resolving paths against the binary path ==

			When resolving an asset path to locate the actual file on disk, the game goes through all defined [binary_path] tags in reverse order of definition. For each binary path, it checks in the following directories, in order:

			* <tt><user data dir>/<binary path>/<type>/<asset path></tt>
			* <tt><game data dir>/<binary path>/<type>/<asset path></tt>
			* <tt><user data dir>/<binary path>/<asset path></tt>
			* <tt><game data dir>/<binary path>/<asset path></tt>

			The <tt><user data dir></tt> is the directory containing the add-ons folder, while the <tt><game data dir></tt> is the directory containing the game data itself – it contains folders <tt>sounds</tt>, <tt>images</tt>, and <tt>data</tt>, at minimum. The <tt><binary path></tt> is the path defined in [binary_path] while the <tt><asset path></tt> is the path being resolved. Finally, <tt><type></tt> is the type of asset being resolved, usually one of <tt>images</tt>, <tt>sounds</tt>, <tt>music</tt>, or <tt>maps</tt>. Lua can define additional types as well.

			Assuming you have loaded the default core, the penultimate binary path to be checked in this process is <tt>data/core</tt>, meaning that built-in assets can be overridden by an add-on simply by creating a file with the same asset path in the add-on's binary path. This binary path is defined by a [binary_path] tag in <tt><game data dir>/data/_main.cfg</tt>. It is expected that alternate cores would define a similar path.

			The final binary path to be checked is the empty string, which means that if an asset is not found in any of the paths defined by [binary_path], then the game checks in the following four directories as a last resort:

			* <tt><user data dir>/<type>/<asset path></tt>
			* <tt><game data dir>/<type>/<asset path></tt>
			* <tt><user data dir>/<asset path></tt>
			* <tt><game data dir>/<asset path></tt>

			This behaviour means that you can build what is called a "binary path independent path" by specifying the path relative to either the <tt><user data dir></tt> or the <tt><game data dir></tt>. These paths are used in contexts where there is no guarantee what the active binary path stack will be, such as [[AchievementsWML]] or the saved game cache.

	== Example ==		== Example ==

Octalot: /* the toplevel [binary_path] tag */ Add support for map_file

2019-12-26T18:22:49Z

the toplevel [binary_path] tag: Add support for map_file

← Older revision		Revision as of 18:22, 26 December 2019
Line 3:		Line 3:

	This tag is used to recognize more than one directory as containing images, music, and sound. It only has one key:		This tag is used to recognize more than one directory as containing images, music, and sound. It only has one key:
	* '''path''': a directory. When an image is not found it the normal ''images'' directory, it will be looked for in '''''path'''/images''. Similarly, music will be looked for in '''''path'''/music'', and sound in '''''path'''/sound''.		* '''path''': a directory. When an image is not found it the normal ''images'' directory, it will be looked for in '''''path'''/images''. Similarly,
			** music will be looked for in '''''path'''/music'', and
			** sound in '''''path'''/sound''.
			** {{DevFeature1.15\|3}} For '''[scenario]map_file''' and '''[replace_map]map_file''', the file will be looked for in '''''path'''/maps''.

	Notice that '''''path''''' is still relative to the main Wesnoth directory.		Notice that '''''path''''' is still relative to the main Wesnoth directory.

Celtic Minstrel: /* Example */ Syntax hiliting

2018-02-27T06:48:24Z

Example: Syntax hiliting

← Older revision		Revision as of 06:48, 27 February 2018
Line 12:		Line 12:
	To enable the game to find images, sounds and music in the add-on MyAddOn:		To enable the game to find images, sounds and music in the add-on MyAddOn:

	[binary_path]		<syntaxhighlight lang=wml>
	path=data/add-ons/MyAddOn		[binary_path]
	[/binary_path]		path=data/add-ons/MyAddOn
			[/binary_path]
			</syntaxhighlight>

	When the game looks for an image '''''units/humans/footman.png''''', it'll now be able to find and use the file '''''MyAddOn/images/units/humans/footman.png'''''.		When the game looks for an image '''''units/humans/footman.png''''', it'll now be able to find and use the file '''''MyAddOn/images/units/humans/footman.png'''''.

Zookeeper: Added an example

2014-03-11T19:02:57Z

Added an example

← Older revision		Revision as of 19:02, 11 March 2014
Line 7:		Line 7:

	[binary_path] should only be used where necessary. For example a multiplayer era should have its [binary_path] inside an #ifdef MULTIPLAYER instead of outside it in order to avoid possible clashes with single-player content.		[binary_path] should only be used where necessary. For example a multiplayer era should have its [binary_path] inside an #ifdef MULTIPLAYER instead of outside it in order to avoid possible clashes with single-player content.

			== Example ==

			To enable the game to find images, sounds and music in the add-on MyAddOn:

			[binary_path]
			path=data/add-ons/MyAddOn
			[/binary_path]

			When the game looks for an image '''''units/humans/footman.png''''', it'll now be able to find and use the file '''''MyAddOn/images/units/humans/footman.png'''''.

	== See Also ==		== See Also ==

Zookeeper: DevFeature removal

2009-03-22T10:50:15Z

DevFeature removal

← Older revision		Revision as of 10:50, 22 March 2009
Line 6:		Line 6:
	Notice that '''''path''''' is still relative to the main Wesnoth directory.		Notice that '''''path''''' is still relative to the main Wesnoth directory.

	~~In Wesnoth 1.4 and earlier releases,~~ [binary_path] ~~was ignored when~~ used ~~inside~~ a ~~MULTIPLAYER symbol conditional, leading to awkward solutions such as:~~		[binary_path] should only be used where necessary. For example a multiplayer era should have its [binary_path] inside an #ifdef MULTIPLAYER instead of outside it in order to avoid possible clashes with single-player content.

	[binary_path]
	~~path=data/campaigns/Era_of_Myths/~~
	~~[/binary_path]~~

	#ifdef MULTIPLAYER
	~~...~~
	~~#endif~~

	~~{{DevFeature}}: [binary_path] can be used in the MULTIPLAYER conditional~~ in ~~the development versions,~~ to avoid possible clashes with single-player content.

	== See Also ==		== See Also ==

ShikadiQueen: /* the toplevel [binary_path] tag */ Mention the [binary_path] vs. MULTIPLAYER issue

2009-01-24T00:19:22Z

the toplevel [binary_path] tag: Mention the [binary_path] vs. MULTIPLAYER issue

@@ Line 5: / Line 5: @@
 * '''path''': a directory. When an image is not found it the normal ''images'' directory, it will be looked for in '''''path'''/images''. Similarly, music will be looked for in '''''path'''/music'', and sound in '''''path'''/sound''.
 Notice that '''''path''''' is still relative to the main Wesnoth directory.
 == See Also ==

Esr: /* the toplevel [binary_path] tag */

2008-02-21T03:40:57Z

the toplevel [binary_path] tag

← Older revision		Revision as of 03:40, 21 February 2008
Line 3:		Line 3:

	This tag is used to recognize more than one directory as containing images, music, and sound. It only has one key:		This tag is used to recognize more than one directory as containing images, music, and sound. It only has one key:
	* ''path'' a directory. When an image is not found it the normal ''images'' directory, it will be looked for in '''''path'''/images''. Similarly, music will be looked for in '''''path'''/music'', and sound in '''''path'''/sound''.		* '''path''': a directory. When an image is not found it the normal ''images'' directory, it will be looked for in '''''path'''/images''. Similarly, music will be looked for in '''''path'''/music'', and sound in '''''path'''/sound''.
	Notice that '''''path''''' is still relative to the main Wesnoth directory.		Notice that '''''path''''' is still relative to the main Wesnoth directory.

Allefant: /* the toplevel [binary_path] tag */

2006-08-13T15:38:36Z

the toplevel [binary_path] tag

← Older revision		Revision as of 15:38, 13 August 2006
Line 2:		Line 2:
	== the toplevel [binary_path] tag ==		== the toplevel [binary_path] tag ==

	This tag is used to recognize more than one directory as containing images, music, and sound.		This tag is used to recognize more than one directory as containing images, music, and sound. It only has one key:
	It only has one key:		* ''path'' a directory. When an image is not found it the normal ''images'' directory, it will be looked for in '''''path'''/images''. Similarly, music will be looked for in '''''path'''/music'', and sound in '''''path'''/sound''.
	* ''path'' a directory. When an image is not found it the normal '''images/''' directory,		Notice that '''''path''''' is still relative to the main Wesnoth directory.
	it will be looked for in '''''path/''images/'''.
	Similarly, music will be looked for in '''''path///music~~/\|\|~~, and sound in ~~\|\|//~~path/''sound/'''.
	Notice that ''path'' is still relative to the main Wesnoth directory.

	== See Also ==		== See Also ==

Placid: /* the toplevel [binary_path] tag */ add tags list

2006-03-21T09:56:49Z

the toplevel [binary_path] tag: add tags list

← Older revision		Revision as of 09:56, 21 March 2006
Line 1:		Line 1:
			{{WML Tags}}
	== the toplevel [binary_path] tag ==		== the toplevel [binary_path] tag ==