TC01
Deity
It's really annoying when you are playing a mod with a mapscript unique to that mod, and then you try to load up unmodded BTS... and you get dozens of python exceptions along the lines of "Custom_Map_Name cannot be found".
Plenty of people seem to not understand what the problem is (and unfortunately many of them are modders), so I thought I'd write this tutorial about it. What's more, a while ago someone requested something like this when having trouble installing mapscripts, I think.
This tutorial is intended to fully explain the difference between private and public maps, and why this difference can cause problems. I was considering just throwing it on the Modiki but I'm not really sure where it should go (other than as a tutorial...) so here it is.
Mapscripts and Scenarios
I thought I'd throw this in here just for clarification, though I doubt it's necessary.
A mapscript is a python file (ending in .py) that generates a random map of a certain type each time.
A scenario, or pre-made map, is a WBS file (either .Civ4WorldBuilderSave, or .CivWarlordsWBSave, or .CivBeyondSwordWBSave, or possibly even .ColonizationWBSave). If you double-click on them, they auto-start Civ with the scenario ready to go, but if you right-click on them and select "Edit" you will find they are actually text files.
Hopefully, this wasn't needed, but you never know.
Public Maps
If you go into the Beyond the Sword directory, you'll see a "PublicMaps" subdirectory. This is where the game stores all of it's mapscripts and scenarios unique to BTS- called public maps. (Ones unique to Warlords or vanilla are stored in their PublicMaps directories).
Why are these maps "public"? Because by default, all mods can access them. So you may be playing Fall from Heaven II, but you can still play a game on the Continents or Donut or Team_Battleground (or whatever) mapscript.
When you install a new mapscript or pre-made map/scenario for BTS, typically you place it here so that you can access it in most mods.
I say "most" mods because there is an option in a mod ini file called "Allow Public Maps". As you might expect, if set to 1, maps in the Vanilla, Warlords, or BTS public maps directories can be loaded. If set to 0, the only maps that can be loaded are ones in a mod's map directories. More on this later.
Private Maps
Now, if a public map can be accessed from anywhere (unless the aforementioned setting in the ini file is set to 0), a private map is one that can only be accessed from the currently loaded mod.
What are the advantages of this? For one, if you're playing Final Frontier, you have access to the FinalFrontier script- and no other mapscripts. FinalFrontier is a script designed specifically for Final Frontier and wouldn't work very well outside of Final Frontier. Likewise, normal mapscripts designed for regular civ wouldn't at all in Final Frontier, so Final Frontier does not allow public maps to be used.
Custom Maps in Mods
You may not be seeing where the problem arises yet.
It does not matter if you place scenarios in a mod's PublicMaps folder. The game is clever enough to build them into the list of all scenarios that can be ran in vanilla BTS (with the caveat that the mod must first be loaded).
But it does matter if you place mapscripts in a mod's PublicMaps folder. Why? Because of this:
I had just finished a Dune Wars game. Whatever mapscript you use is logged to the ini file. Because Dune Wars' custom mapscripts are stored in a PublicMaps folder, rather than a PrivateMaps folder, the game tries to load that mapscript for some reason after initializing everything (the XML, audio, Python, engine, fonts, all of it).
But it isn't clever enough to detect the Arrakis mapscript, because it's in a mod folder. So you get errors like this:
And this:
Several times when the game first starts and then whenever you enter the Single Player menu (if the game was single player, which it was- I imagine it would happen in the multiplayer menus if the game was multiplayer).
Now, if I play a game using the FinalFrontier mapscript, using the Final Frontier mod (which uses Private, instead of Public, maps), this doesn't happen. The map is still logged:
But the game doesn't try to load it- it knows it's a private mapscript and can't access it.
So what it boils down to is that the game doesn't see mapscripts in a mod's PublicMaps folder as truly "public". But it does see scenarios. And what's more, the last scenario you play isn't logged to the ini file and the game doesn't try to load it. After playing a Crossroads of the World game, the ini still says my last game was on a FinalFrontier map.
How to Avoid Problems
If your mod has custom mapscripts and scenarios, here is ideally how they should be set up.
Your_Mod\PrivateMaps: All mapscripts unique to your mod should be placed here.
Your_Mod\PublicMaps: If you have scenarios unique to your mod (WBS files) and if their ModPath is set to "Mods\Your_Mod", feel free to place the scenarios here so that they can be loaded directly from the main menu. Otherwise, keep them in PrivateMaps.
Don't place custom mapscripts in Your_Mod\PublicMaps!
Disclaimer
I just want to add that I'm not knocking the Dune Wars mod or anything- I was just trying to find a mod with mapscripts set up the "wrong way" and Dune Wars was the first one I had installed that I could see.
Plenty of people seem to not understand what the problem is (and unfortunately many of them are modders), so I thought I'd write this tutorial about it. What's more, a while ago someone requested something like this when having trouble installing mapscripts, I think.
This tutorial is intended to fully explain the difference between private and public maps, and why this difference can cause problems. I was considering just throwing it on the Modiki but I'm not really sure where it should go (other than as a tutorial...) so here it is.
Mapscripts and Scenarios
I thought I'd throw this in here just for clarification, though I doubt it's necessary.
A mapscript is a python file (ending in .py) that generates a random map of a certain type each time.
A scenario, or pre-made map, is a WBS file (either .Civ4WorldBuilderSave, or .CivWarlordsWBSave, or .CivBeyondSwordWBSave, or possibly even .ColonizationWBSave). If you double-click on them, they auto-start Civ with the scenario ready to go, but if you right-click on them and select "Edit" you will find they are actually text files.
Hopefully, this wasn't needed, but you never know.
Public Maps
If you go into the Beyond the Sword directory, you'll see a "PublicMaps" subdirectory. This is where the game stores all of it's mapscripts and scenarios unique to BTS- called public maps. (Ones unique to Warlords or vanilla are stored in their PublicMaps directories).
Why are these maps "public"? Because by default, all mods can access them. So you may be playing Fall from Heaven II, but you can still play a game on the Continents or Donut or Team_Battleground (or whatever) mapscript.
When you install a new mapscript or pre-made map/scenario for BTS, typically you place it here so that you can access it in most mods.
I say "most" mods because there is an option in a mod ini file called "Allow Public Maps". As you might expect, if set to 1, maps in the Vanilla, Warlords, or BTS public maps directories can be loaded. If set to 0, the only maps that can be loaded are ones in a mod's map directories. More on this later.
Code:
; Allow public maps to be used with this mod
AllowPublicMaps = 1Private Maps
Now, if a public map can be accessed from anywhere (unless the aforementioned setting in the ini file is set to 0), a private map is one that can only be accessed from the currently loaded mod.
What are the advantages of this? For one, if you're playing Final Frontier, you have access to the FinalFrontier script- and no other mapscripts. FinalFrontier is a script designed specifically for Final Frontier and wouldn't work very well outside of Final Frontier. Likewise, normal mapscripts designed for regular civ wouldn't at all in Final Frontier, so Final Frontier does not allow public maps to be used.
Custom Maps in Mods
You may not be seeing where the problem arises yet.
It does not matter if you place scenarios in a mod's PublicMaps folder. The game is clever enough to build them into the list of all scenarios that can be ran in vanilla BTS (with the caveat that the mod must first be loaded).
But it does matter if you place mapscripts in a mod's PublicMaps folder. Why? Because of this:
Code:
; Map Script file name
Map = ArrakisI had just finished a Dune Wars game. Whatever mapscript you use is logged to the ini file. Because Dune Wars' custom mapscripts are stored in a PublicMaps folder, rather than a PrivateMaps folder, the game tries to load that mapscript for some reason after initializing everything (the XML, audio, Python, engine, fonts, all of it).
But it isn't clever enough to detect the Arrakis mapscript, because it's in a mod folder. So you get errors like this:
Code:
Traceback (most recent call last):
File "<string>", line 1, in ?
ImportError: No module named ArrakisAnd this:
Code:
Failed to load python module Arrakis.Several times when the game first starts and then whenever you enter the Single Player menu (if the game was single player, which it was- I imagine it would happen in the multiplayer menus if the game was multiplayer).
Now, if I play a game using the FinalFrontier mapscript, using the Final Frontier mod (which uses Private, instead of Public, maps), this doesn't happen. The map is still logged:
Code:
; Map Script file name
Map = FinalFrontierBut the game doesn't try to load it- it knows it's a private mapscript and can't access it.
So what it boils down to is that the game doesn't see mapscripts in a mod's PublicMaps folder as truly "public". But it does see scenarios. And what's more, the last scenario you play isn't logged to the ini file and the game doesn't try to load it. After playing a Crossroads of the World game, the ini still says my last game was on a FinalFrontier map.
How to Avoid Problems
If your mod has custom mapscripts and scenarios, here is ideally how they should be set up.
Your_Mod\PrivateMaps: All mapscripts unique to your mod should be placed here.
Your_Mod\PublicMaps: If you have scenarios unique to your mod (WBS files) and if their ModPath is set to "Mods\Your_Mod", feel free to place the scenarios here so that they can be loaded directly from the main menu. Otherwise, keep them in PrivateMaps.
Don't place custom mapscripts in Your_Mod\PublicMaps!
Disclaimer
I just want to add that I'm not knocking the Dune Wars mod or anything- I was just trying to find a mod with mapscripts set up the "wrong way" and Dune Wars was the first one I had installed that I could see.
