BinaryPathWML - Revision history

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

2023-07-23T14:35:36Z

‎Resolving paths against the binary path: New section

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

Celtic Minstrel: /* Example */ Syntax hiliting

2018-02-27T06:48:24Z

‎Example: Syntax hiliting

Zookeeper: Added an example

2014-03-11T19:02:57Z

Added an example

Zookeeper: DevFeature removal

2009-03-22T10:50:15Z

DevFeature removal

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

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

2008-02-21T03:40:57Z

‎the toplevel [binary_path] tag

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

2006-08-13T15:38:36Z

‎the toplevel [binary_path] tag

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

2006-03-21T09:56:49Z

‎the toplevel [binary_path] tag: add tags list

Jorda at 11:29, 20 January 2006

2006-01-20T11:29:26Z

← 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 ==

@@ 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:
-* '''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,
 Notice that '''''path''''' is still relative to the main Wesnoth directory.

@@ Line 12: / Line 12: @@
 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
 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'''''.

← 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 ==

@@ Line 6: / Line 6: @@
 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.
 == See Also ==

← 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 ==

← Older revision		Revision as of 11:29, 20 January 2006
Line 12:		Line 12:
	* [[ReferenceWML]]		* [[ReferenceWML]]

		+
		+	[[Category: WML Reference]]