File path rules

[Helmet]

Why do file paths stop working when they are more specific?

For example, this was the bug that stopped an image from appearing within an [object] tag:

image=images/items/basket.png

This was the solution:

image=items/basket.png

But this won't work:

image=basket.png

What are the WML rules about file paths? When do you need a tilde: ~ ?

When should a file path start with a / ?

I found this file path somewhere. Two dots? Why does it work? symbol_image=../scenery/signpost

Thanks!

[Lord-Knightmare]

I think this has to do with binary paths.
If you include the binary path to your campaign it immediately recognizes the images directory for some reason.
The tilde is when you directly include the raw path:
~add-ons/My_Addon_UMC/images/units/my-fancy-unit.png

Hope this helps. I found these out myself during my many scenario designing endeavors.

[Pentarctagon]

It's related to the [binary_path] being set. An image is searched for first in the core game files, then in <binary_path>/images/. So for example image=images/items/basket.png is evaluated as image=images/images/items/basket.png, image=items/basket.png becomes image=images/items/basket.png, and so on.

[Helmet]

I think this has to do with binary paths.
If you include the binary path to your campaign it immediately recognizes the images directory for some reason.
The tilde is when you directly include the raw path:
~add-ons/My_Addon_UMC/images/units/my-fancy-unit.png

Hope this helps. I found these out myself during my many scenario designing endeavors.

Thanks, that was very helpful.

It's related to the [binary_path] being set. An image is searched for first in the core game files, then in <binary_path>/images/. So for example image=images/items/basket.png is evaluated as image=images/images/items/basket.png, image=items/basket.png becomes image=images/items/basket.png, and so on.

Ah! I recall having seen an images folder within an images folder in a campaign somewhere, so image=images/images/items/basket.png could be an actual folder as far as the game engine is concerned. So the game only looked where I told it to, which was a folder that doesn't exist. Thanks for clearing that up. I kept making similar file-path mistakes and it was starting to bug me, but I shouldn't make them any more. Whew.

I tried a few variations, by the way. These all work:
image=items/basket.png
/image=items/basket.png << EDIT : DO NOT DO THIS. Old method will be phased-out.
"image=items/basket.png" << EDIT : DO NOT DO THIS. Old method will be phased-out.
"/image=items/basket.png" << EDIT : DO NOT DO THIS. Old method will be phased-out.

If there's another variation that works, please let me know.

Also, I think most coders don't bother with the " " or the initial / .

Thanks again!

[Pentarctagon]

The image= is the attribute that stores the path; it has nothing to do with the path itself. You should also never ever do things like the last three - they may or may not work in any particular place in your code, or in any future version of wesnoth - either image=items/basket.png or image="items/basket.png" is correct.

[Helmet]

The image= is the attribute that stores the path; it has nothing to do with the path itself.

image= stores the path? So...it's a container, like a variable. I thought it was like message, which actually does something with the text in-between the quotes.

Oh, wait. Maybe message only stores the message in quotes?

Oh. Man. So much of my thinking was wrong.

You should also never ever do things like the last three - they may or may not work in any particular place in your code, or in any future version of wesnoth - either image=items/basket.png or image="items/basket.png" is correct.

Thanks for the info.

[Pentarctagon]

No attributes or WML tags do anything directly themselves; they're all read by the engine, stored as variables and containers internally, and then after that used by the engine to do something.

As an example, [object]'s logic is actually defined in lua here.

[Helmet]

No attributes or WML tags do anything directly themselves; they're all read by the engine, stored as variables and containers internally, and then after that used by the engine to do something.

As an example, [object]'s logic is actually defined in lua here.

I think I understand the basic idea now.

WML collects data from the player and the game via keys/tags, and Lua code takes the data and makes the game work.

Boy, I'm glad we can use WML to make games instead of Lua. The LUA code you showed me made my eyes go .

[Lord-Knightmare]

The LUA code you showed me made my eyes go .

You can try having a look at moonscript. It's a dynamic scripting programming language that compiles to Lua. It's a lot more appealing to the eyes and introduces convenience. Their home page even shows a comparison between a sample moonscript and the corresponding Lua code it compiles to. I was considering to use it to make Lua code for a UMC.

[Pentarctagon]

The LUA code you showed me made my eyes go .

You can try having a look at moonscript. It's a dynamic scripting programming language that compiles to Lua. It's a lot more appealing to the eyes and introduces convenience. Their home page even shows a comparison between a sample moonscript and the corresponding Lua code it compiles to. I was considering to use it to make Lua code for a UMC.

The "compiles to Lua" part is very important though, since Wesnoth by itself won't understand Moonscript.

[Helmet]

You can try having a look at moonscript. It's a dynamic scripting programming language that compiles to Lua. It's a lot more appealing to the eyes and introduces convenience. Their home page even shows a comparison between a sample moonscript and the corresponding Lua code it compiles to. I was considering to use it to make Lua code for a UMC.

I checked it out. The code does seem much easier to grasp, which is appealing. So far, about everything I truly want to include in my scenarios can be done with WML. Eventually, though, I may find myself needing another solution, so thanks for the tip.

[Celtic_Minstrel]

/image=items/basket.png << EDIT : DO NOT DO THIS. Old method will be phased-out.
"image=items/basket.png" << EDIT : DO NOT DO THIS. Old method will be phased-out.
"/image=items/basket.png" << EDIT : DO NOT DO THIS. Old method will be phased-out.

I'm really confused, because these three should never work in any version of the game. They're a direct violation of WML syntax rules, so if they somehow work, it's only because of a bug in the WML parser.

Why do file paths stop working when they are more specific?

For example, this was the bug that stopped an image from appearing within an [object] tag:

image=images/items/basket.png

This was the solution:

image=items/basket.png

But this won't work:

image=basket.png

What are the WML rules about file paths?

This is the binary path, as Pentarctagon explained. When you give an image file path, Wesnoth gathers all the [binary_path] tags in the game and searches for an images folder in each one, and then looks for the image in each of those folders. Pentarctagon already explained how that trannslates for your three examples, so I won't repeat that.

Side note: I'm not 100% sure, but I think you can also write an "absolute" path for an image. Such a path would look like data/add-ons/Your_Campaign/images/items/basket.png and probably means you don't need a binary path. I wouldn't recommend doing this though.

When do you need a tilde: ~ ?

The tilde only has a meaning in WML or Lua paths, not in image paths. That is, you can only use it if giving a path to a WML or Lua file. A tilde must always be followed by the name add-ons and just means that the path is in the add-ons directory instead of the core data directory.

When should a file path start with a / ?

I'm not sure if there's any reason to start a file path with /, but if there is, it's probably also just for WML or Lua files, indicating that the path is in the core data directory instead of the add-ons directory.

I found this file path somewhere. Two dots? Why does it work? symbol_image=../scenery/signpost

This is terrain graphics, which follow slightly different rules. They check the binary path and look for an images folder as normal, but then they look for the terrain folder and find the path in there. Those two dots signal that it shouldn't be looking in the terrain folder and should instead find the scenery folder directly in the images folder - in other words, it goes up a level in the directory structure. In 1.15, the two dots also work for WML and Lua paths, but you can't access files that aren't in the add-ons or core data directories.

[Helmet]

I'm really confused, because these three should never work in any version of the game. They're a direct violation of WML syntax rules, so if they somehow work, it's only because of a bug in the WML parser.

I mistyped the fourth one: I meant /image="items/basket.png" not "/image=items/basket.png" So that one would not work.
The others did work, though. I'm using 1.15.6.

Side note: I'm not 100% sure, but I think you can also write an "absolute" path for an image. Such a path would look like data/add-ons/Your_Campaign/images/items/basket.png and probably means you don't need a binary path. I wouldn't recommend doing this though.

I almost asked that question. Thanks.

The tilde only has a meaning in WML or Lua paths, not in image paths. That is, you can only use it if giving a path to a WML or Lua file. A tilde must always be followed by the name add-ons and just means that the path is in the add-ons directory instead of the core data directory.

Ohhh. I was hoping it might be more useful than that. Good to know.

This is terrain graphics, which follow slightly different rules. They check the binary path and look for an images folder as normal, but then they look for the terrain folder and find the path in there. Those two dots signal that it shouldn't be looking in the terrain folder and should instead find the scenery folder directly in the [/c]images[/] folder - in other words, it goes up a level in the directory structure. In 1.15, the two dots also work for WML and Lua paths, but you can't access files that aren't in the add-ons or core data directories.

Uh oh. I've been inventing my own folder structure. Worse, I rename folders to names I like better!

What is the "best practices" folder structure?

[Celtic_Minstrel]

What is the "best practices" folder structure?

Images go in Your_Addon/images, terrain graphics go in Your_Addon/images/terrain, sound effects go in Your_Addon/sounds, music tracks go in Your_Addon/translations, and translation catalogues go in Your_Addon/translations. Those are all the things that are loaded based on a [binary_path] - everything else can go pretty much wherever you want.

But you asked for "best" practices, so I'll list a few more suggested locations for other types of files.

• Scenario configs go in Your_Addon/scenarios.
• Map and mask files go in Your_Addon/maps.
• Terrain definitions go in Your_Addon/terrain.
• Unit type definitions (as well as other other unit-related things such as races and movetypes) go in Your_Addon/units.
• Macro definitions go in Your_Addon/macros or Your_Addon/utils.
• Lua files go in Your_Addon/lua. This is especially important for Lua modules, as placing them in a "lua" folder allows them to be loaded from other Lua code via a simple wesnoth.require "module_name", where "module_name" is the name of the file without the .lua suffix. If you put Lua files somewhere else (eg in a "utils" folder), then you would need the path to load it (eg wesnoth.require "utils/module_name").

[Helmet]

Thank you, Celtic_Minstrel; that was very helpful. I renamed my "sounds" folder to "audio", and made other adjustments to my file structure.

...music tracks go in Your_Addon/translations

I think you meant music tracks go in Your_Addon/music.

[*]Terrain definitions go in Your_Addon/terrain.

I'm not familiar with the term "terrain definitions." Is a definition that same as .cfg? I thought terrain.cfg and terrain_graphics go in Your_Addon/utils?

[*]Unit type definitions (as well as other other unit-related things such as races and movetypes) go in Your_Addon/units.

I have several custom attack icons, such as military_fork.png. I put them in Your_Addon/images/attacks. Should I use Your_Addon/images/icons instead?

I have the following folders within the images folder: halo, icons, items, portraits, projectiles, scenery, story. And I have a custom .png depicting a zoomed-in view of the Wesnoth map, which I put in Your_Addon/images/maps. Correct?

I made an animated title 180 frames long for my campaign. I decided to put the frames in a folder call title in Your_Addon/images. I almost named the folder animation, so I could put other animated sequences in it. What would you do?

I have a lot of custom units, so my images folder now contains a lot of files (halo, icons, etc.). I kinda would like a folder that is only custom units. Is that a bad idea? If not, what would you call a folder containing nothing but custom unit images, and where would you place it?

Lastly, would you define or describe a "cut-scene" in Wesnoth? I've heard the term used in at least two different ways, but I don't recall ever seeing a cut_scene folder. I have seen a movies folder, however.