[Wesnoth-wiki-changes] BuildingCampaigns

[wiki]

UserAgent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.3) Gecko/20041007 
Debian/1.7.3-5
IP: 64.81.113.168
URI: http://wesnoth.slack.it/?BuildingCampaigns
 - - - - -
Index: BuildingCampaigns
===================================================================
RCS file: /home/wesnoth/cvsroot/wikiroot/BuildingCampaigns,v
retrieving revision 1.4
diff -u -r1.4 BuildingCampaigns
--- BuildingCampaigns   13 Sep 2004 07:14:32 -0000      1.4
+++ BuildingCampaigns   4 Nov 2004 23:24:00 -0000
@@ -26,26 +26,42 @@
 There is a standard way to do this, which is prescribed in a forum thread at:
 http://www.wesnoth.org/forum/viewtopic.php?t=1917
 
-First of all some terminology.  All wesnoth's built-in data files live inside 
a directory I'll call the //wesnoth
-path//.  The name of this directory varies from system to system; on many unix 
systems, it is
-"/usr/local/share/wesnoth".  You can make wesnoth tell you what it is on your 
system by running "wesnoth --path".  All
-of the built-in WML lives in a subdirectory called "data" under the wesnoth 
path, which I'll call the //wesnoth data
-directory//.  User campaigns can be installed in here - call this a //system 
install//.  There is also a directory
-outside the wesnoth path, which I'll call the //wesnoth user directory//.  
This is where saved games go, among other
-things, and (I believe) user campaigns can be installed here too - call this a 
//user install//.  On typical unix
-systems, the wesnoth user directory is called "~/.wesnoth".
-
-There's a notation that's used by the WML preprocessor for files under the 
wesnoth data directory: {filename.cfg}, and
-for files under the wesnoth user directory {~filename.cfg}.  I'll use that too.
-
-So, when wesnoth starts, it loads every file in the directories {campaigns} 
and {~campaigns}.  To install a campaign,
-you need to place a file in one of those places - call this your //campaign 
file//.  You should name this file after
-your campaign, replacing spaces with underscores. e.g. "Sample_Campaign.cfg".  
To do a system install, you would place
-this file in {campaigns} (i.e. if your system is like mine,
-/usr/local/share/wesnoth/data/campaigns/Sample_Campaign.cfg), to do a user 
install,
-place it in {~campaigns}.  Your campaign file should contain three things: 1) 
a WML [campaign] tag, 2) WML preprocessor
-instructions to load your scenarios, units, etc. and 3) (if your campaign adds 
images or sounds) a [binary_path] tag to
-help load those files.
+First of all some terminology.
+All wesnoth's built-in data files live inside a directory I'll call the 
//wesnoth path//.
+The name of this directory varies from system to system;
+on many unix systems, it is ||/usr/local/share/wesnoth||.
+You can make wesnoth tell you what it is on your system by running "wesnoth 
--path".
+All of the built-in WML lives in the subdirectory ||data/|| of wesnoth-path,
+which I'll call the //wesnoth data directory//.
+User campaigns can be installed in here - call this a //system install//.
+There is also a directory outside the wesnoth path, which I'll call the 
//wesnoth user directory//.
+This is where saved games go, among other things, and (I believe) user 
campaigns can be installed here too
+- call this a //user install//.
+On typical unix systems, the wesnoth user directory is called ||~/.wesnoth||.
+On Windows, it is called ||<i>wesnoth-path</i>\Userdata||.
+On MacOSX, it is called 
||<i>user-home-directory</i>\Library\Preferences\Wesnoth\||.
+
+There's a notation that's used by the WML preprocessor for files under the 
wesnoth data directory:
+||{filename.cfg}||, and for files under the wesnoth user directory 
||{~filename.cfg}||.
+(For more information on these see PreprocessorWML).
+I'll use that too.
+
+So, when Wesnoth starts, it loads every file in the directories {campaigns} 
and {~campaigns}.
+To install a campaign, you need to place a file in one of those places
+- call this your //campaign file//.
+You should name this file after your campaign, replacing spaces with 
underscores.
+e.g. "Sample_Campaign.cfg".
+To do a system install, you would place this file in {campaigns}
+(i.e. if your system is like mine,
+/usr/local/share/wesnoth/data/campaigns/Sample_Campaign.cfg),
+to do a user install, place it in {~campaigns}.
+Your campaign file should contain three things:
+
+1) a WML [campaign] tag,
+
+2) WML preprocessor instructions to load your scenarios, units, etc. and
+
+3) (if your campaign adds images or sounds) a [binary_path] tag to help load 
those files.
 
 For reference documentation on this, see CampaignWML.
 
@@ -54,11 +70,11 @@
  [campaign]
  id=sample_campaign
  icon=some_icon.png
- name=Sample Campaign
+ name= _ "Sample Campaign"
  define=CAMPAIGN_SAMPLE_CAMPAIGN
  first_scenario=some_scenario_id
  difficulties=EASY,NORMAL,HARD
- difficulty_descriptions=some_description
+ difficulty_descriptions= _ 
"&easy_icon.png,Easy;*&normal_icon.png,Normal;&hard_icon.png,Hard"
  [/campaign]
 
  [+units]
@@ -76,23 +92,38 @@
  [/binary_path]
  #endif
 
-There are two important features of this that aren't self-explanatory.  First, 
the use of the #ifdef.  Wesnoth loads its
-configuration once at startup, and then again when you start playing.  The 
first time, CAMPAIGN_SAMPLE_CAMPAIGN will not
-be defined, and your scenarios will not be loaded, nor will the [binary_path] 
tag be used.  The second time, if the user
-is playing your campaign, CAMPAIGN_SAMPLE_CAMPAIGN will be defined, and the 
scenarios will be loaded.  This prevents
-your campaign from treading on others' toes (for example, if two user campaign 
are installed this way, they can both
-give the same name to a scenario without clashing).  It also means that you 
can customise global wesnoth settings (the
-terrain configuration, for example) on a per-campaign basis.
-
-Second, the [binary_path] tag allows images and sounds to be installed inside 
the {campaigns/Sample_Campaign} directory
-(built-in images and sounds are right outside the wesnoth data directory).
-
-Now, you install all the rest of your campaign under the directory 
{campaigns/Sample_Campaign}.  Maps go in
-{campaigns/Sample_Campaign/maps}, scenarios go in 
{campaigns/Sample_Campaign/scenarios}, images go in
-{campaigns/Sample_Campaign/images}, and so on.  This makes it easy for a user 
to delete your campaign from their system.
-
-You can refer to your images, installed this way, as "some-image.png" (that's 
the work of [binary_path]), and
-include maps by using the preprocessor syntax 
{campaigns/Sample_Campaign/maps/mymap} with the map_data attribute.  You
+There are two important features of this that aren't self-explanatory.
+First, the use of the #ifdef.
+Wesnoth loads its configuration once at startup, and then again when you start 
playing.
+The first time, CAMPAIGN_SAMPLE_CAMPAIGN will not be defined, and your 
scenarios will not be loaded,
+nor will the [binary_path] tag be used.
+The second time, when the user starts your campaign,
+CAMPAIGN_SAMPLE_CAMPAIGN will be defined, and the scenarios will be loaded.
+This prevents your campaign from treading on others' toes
+(for example, if two user campaign are installed this way,
+they can both give the same name to a scenario without clashing).
+It also means that you can customise global wesnoth settings
+(the terrain configuration, for example) on a per-campaign basis.
+However, notice that [+units] is not inside the #ifdef.
+This is due to a bug in Wesnoth programming that causes
+savegames in your campaign to be corrupt if you try to put it in.
+Unfortunately, this means that you need to make sure that
+none of your units conflict with other user or mainline units.
+
+Second, the [binary_path] tag allows images and sounds to be installed inside 
the
+{campaigns/Sample_Campaign} directory instead of the default Wesnoth path.
+(Note: If you want to use one of these images as your campaign icon,
+you need to move [binary_path] out of the #ifdef.)
+
+Now, you install all the rest of your campaign under the directory 
{campaigns/Sample_Campaign}.
+Maps go in {campaigns/Sample_Campaign/maps}, scenarios go in 
{campaigns/Sample_Campaign/scenarios},
+images go in {campaigns/Sample_Campaign/images}, and so on.
+This makes it easy for a user to delete your campaign from their system,
+and is required in order to upload it to the campaign server (see bottom).
+
+You can refer to your images, installed this way, as "some-image.png"
+(that's the work of [binary_path]), and include maps by using the preprocessor 
syntax
+"{campaigns/Sample_Campaign/maps/mymap}{~campaigns/Sample_Campaign/maps/mymap}"
 with the map_data attribute.  You
 might also define a preprocessor macro to abstract away from the title of your 
campaign.  For example, you might write
 the end of the campaign file like this:
 
@@ -100,7 +131,7 @@
  #ifdef CAMPAIGN_SAMPLE_CAMPAIGN
 
  #define MAP NAME
-   map_data="{campaigns/Sample_Campaign/maps/{NAME}}"
+   
map_data="{campaigns/Sample_Campaign/maps/{NAME}}{~campaigns/Sample_Campaign/maps/{NAME}}"
  #enddef
 
  {campaigns/Sample_Campaign/scenarios}
@@ -111,45 +142,71 @@
  [/binary_path]
  #endif
 
-Now your scenarios can refer to their maps by saying "{MAP mymap}", without 
having to know the name of the campaign
-they're included in, which might be helpful - if you ever change the name of 
your campaign, you don't want to edit all
-the scenarios.
+Now your scenarios can refer to their maps by saying "{MAP mymap}",
+without having to know the name of the campaign they're included in, which 
might be helpful
+- if you ever change the name of your campaign, you don't want to have to edit 
all the scenarios.
 
 Units are special.  At the moment, they must be shared between all campaigns 
(but units that are being installed by your
 campaign should still live under {campaigns/Your_Campaign_Name/units}).  So be 
careful when creating units not to use
-unit names that someone else is using. This also means that the units have to 
be declared outside the #ifdef, as in the example
-above. If you mistakenly declare them inside the #ifdef, the scenarios most 
likely will load, but savegames will fail.
-
-Beware: for legacy reasons, the MainlineScenarios don't follow these 
guidelines.  In particular, they don't keep all
-their data inside a single directory (this is also because they share data), 
and they don't conditionally include their
-scenarios.  Don't copy them, or you will find it hard to change later, and 
your campaign is likely to clash with other
-user campaigns.
+unit names that someone else is using. This also means that the units have to 
be declared outside the #ifdef, as in the
+example above. If you mistakenly declare them inside the #ifdef, the scenarios 
most likely will load, but savegames will
+fail.
+
+Beware: for legacy reasons, the MainlineScenarios don't follow these 
guidelines.
+In particular, they don't keep all their data inside a single directory (this 
is also because they share data),
+and they don't conditionally include their scenarios.
+Don't copy them, or you will find it hard to change later,
+and your campaign is likely to clash with other user campaigns.
 
 ||Packaging your campaign||
 
-For other users to play your campaign, you need to package it into a form that 
they can download and install themselves.
-There are (at least) two ways to do this: First, you can package your campaign 
into an archive with a script (e.g. a
-shell script, a batch file, or a makefile) that will install your campaign 
onto the user's system.  If you do this, bear
-in mind that the user might not have the same directory layout as you: 
"wesnoth --path" can be helpful here.  The
-advantage of this is that you get to have a lot of control over how your 
campaign is installed - and your script can do
-things like checking whether the wesnoth version is adequate for your 
campaign, and alerting the user if it's not.  Also
-bear in mind that many scripting languages are not portable to every platform 
wesnoth supports.
-
-Second, you could package your campaign as an //installed image//: that is, an 
archice of the campaign files in the
-layout they will be after installation.  That way, the user can simply unpack 
it in the appropriate place.
+For other users to play your campaign,
+you can either upload it to the campaign server (see Campaign Server),
+or package it into a form that they can download and install themselves.
+There are (at least) two ways to do this:
+First, you can package your campaign into an archive with a script
+(e.g. a shell script, a batch file, or a makefile)
+that will install your campaign onto the user's system.
+The advantage of this is that you get to have a lot of control over how your 
campaign is installed
+- and your script can do things like checking whether the wesnoth version is 
adequate for your campaign,
+and alerting the user when it's not.
+However, if you do this, bear in mind that the user might not have the same 
directory layout as you:
+"wesnoth --path" can be helpful here.
+Still, many scripting languages are not portable to every platform Wesnoth 
supports.
+
+Second, you could package your campaign as an //installed image//:
+that is, an archive of the campaign files in the layout they will be after 
installation.
+That way, the user can simply unpack it in the appropriate place.
 
 I think doing both is a good idea. Scripts make campaigns easier and more 
reliable to install, but are not generally
 portable.  Images can be installed on any system that has the right archiving 
software (e.g. zip) but are harder to install.
 
 ||Distributing your campaign||
 
-When you're ready to distribute your campaign, make an entry for it in the 
UserScenarios wiki topic, and start a thread
-about it in the Scenario and Campaign Development forum:
+When you're ready to distribute your campaign, make an entry for it in the 
UserScenarios wiki topic,
+and start a thread about it in the Scenario and Campaign Development forum:
 
 http://www.wesnoth.org/forum/viewforum.php?f=8
 
-You can also upload your campaign to the forum as an attachment, if you do not 
have a web or ftp server of your own to
-upload it to.
+You can also upload your campaign to the forum as an attachment,
+if you do not have a web or ftp server of your own to upload it to.
+
+||Campaign server||
+As of 0.8.5, there is an easier way to package/distribute your campaign.
+First, make sure all files used in your campaign are in
+||<i>wesnoth-user-path</i>/<i>your_campaign_name</i>/|| and 
||<i>wesnoth-user-path</i>/<i>your_campaign_name</i>.cfg||.
+(They should be if you have followed the instructions on this page).
+Second, make a //PBL file// for your campaign.
+The syntax for this is described in PblWML.
+Your PBL file should be 
||<i>wesnoth-user-path</i>/<i>your_campaign_name</i>.pbl||.
+Finally, to upload your campaign, enter Wesnoth, click "Campaign",
+go to "Get More Campaigns", and connect to "campaigns.wesnoth.org" (this 
should be the default).
+Then, click on "Publish Campaign: Your Campaign" at the bottom of the page.
+To release a new version of your campaign, do the same thing.
+
+Even if you release your campaign on the campaign server, it is a good idea
+to start a thread about it in the Scenario and Campaign Development forum
+so that your campaign can be noticed and discussed.
=20
 ||See Also||