Changes in WikiSandbox
Revision Differences of Revision 77
Test [[ wikisyntax | wiki syntax ]] here :-) ¶¶
[TOC] ¶
¶
Some initial help for creating a campaign. What you should know before reading on: ¶
¶
* [First steps for a scenario](https://wl.widelands.org/docs/wl/tutorial/) ¶
* Make sure to use a plain text editor when writing scripts ¶
¶
## init.lua ¶
¶
You have read that the file `scripting/init.lua` is the main entry for your scenario. So this file is the starting point and should contain necessary global settings. This file contains usually different parts: ¶
¶
### Including global fnctionality ¶
¶
~~~~ ¶
include "scripting/coroutine.lua" ¶
include "scripting/messages.lua" ¶
include "scripting/ui.lua" ¶
~~~~ ¶
¶
The files which get included here contain functions which you may need in your project. E.g. the file `coroutine.lua` contain a function `sleep(time)`. Those files (and their functions) are described in [Auxiliary Scripts](https://wl.widelands.org/docs/wl/autogen_toc_auxiliary/). Please take a look at the includes above and look into the auxiliary scripts documentation to get knowledge about their functions. Don't worry if you don't understand that much at the moment. Later on we will see how to use them. ¶
¶
### Global variables ¶
¶
In this part of the `init.lua` we define variables which we want to be available each time. That's why they are called 'global' variables. This global variables are shortcuts and prevent writing each time the same: ¶
¶
~~~~ ¶
plr = wl.Game().players[1] ¶
map = wl.Game().map ¶
plr_sf = map.player_slots[1].starting_field ¶
~~~~ ¶
¶
What this code does: ¶
¶
* `plr = wl.Game().players[1]`: This reads the first defined player of the map and assign it to the variable 'plr'. You have to set the player(s) in the map editor to get this to work. ¶
* `map = wl.Game().map`: The variable 'map' gives you now access to many properties of the map itself, e.g. to the function `get_field()` in [Map](https://wl.widelands.org/docs/wl/autogen_wl_map/#wl.map.Map). This will be the most used function in your scenario. ¶
* `plr_sf = map.player_slots[1].starting_field`: You have set a player in the map editor on a field, so this assigns this field to the global variable 'plr_sf'. Note that we use here already the variable 'map' which we have defined one line above. Also note that there is a point between 'map', 'player_slots' and 'starting_field'. I tell you later why this is important. ¶
¶
### Including the main control script ¶
¶
Now we are ready with initialization and can work on to get the story alive. To split of initialization and other stuff, we include another file in the last line in our `init.lua` : ¶
¶
~~~~ ¶
include "map:scripting/story_script.lua" ¶
~~~~ ¶
¶
The file `story_script.lua` will contain the main thread for our scenario. The include at the end of the `init.lua` makes sure all other initialization is done and all defined variables are available in each further included file. ¶
¶
## story_script.lua ¶
¶
In this file we create our scenario and add conditions and objectives a player has to fulfill. ¶
¶
The map you have created is empty by default. You have set a player, but no buildings at all. It is our part to place buildings. ¶
¶
###
¶
First we place the headquarters for player 1. Do you remember you have set the global variables `plr` and `plr_sf`? Here we use them: ¶
¶
~~~~ ¶
hq = plr:place_building("empire_headquarters", plr_sf, false, true) ¶
~~~~ ¶
¶
We call the function [place_building()](https://wl.widelands.org/docs/wl/autogen_wl_bases/#wl.bases.PlayerBase) with the needed arguments (the entries in the brackets). The first argument for the function is a string. You could find the right string in the corresponding file init.lua of the building in the subfolders of _'data/tribes/buildings/'_. You need the string of the _'name'_ attribute here. Note the colon between `plr` and the functions name. Do you remember that we had already a point as a separator? Time for a small explanation about the difference between point and colon: ¶
¶
Consider to have an object like a car. This car has a property: color. But this car has also some functions: drive_straight(), drive_left(), drive_right(). If you want to get the color, you want to access the property: `clr = car.color.` If you want to drive the car you need to call the functions: `car:drive_straight(100 meter)`. Do you see the difference? Accessing a property needs a point, calling a function needs a colon! ¶
¶
Now its time for a first test. Run: ¶
¶
~~~~ ¶
./widelands --scenario=/full/path/to/the/map.wmf ¶
~~~~ ¶
¶
You should see the placed headquarters after loading is complete. Look at the stock... the headquarters is empty, no wares and workers are in it. We should change that. ¶
¶
###
¶
The function [place_building()](https://wl.widelands.org/docs/wl/autogen_wl_bases/#wl.bases.PlayerBase) returns a reference to the created building. We have assigned this reference to the variable `hq`. Now we can use this variable and the function [set_wares()](https://wl.widelands.org/docs/wl/autogen_wl_map/#wl.map.HasWares.set_wares) to fill the building: ¶
¶
~~~~ ¶
hq:set_wares("log",10) ¶
hq:set_wares("planks",10) ¶
hq:set_wares("granite",10) ¶
~~~~ ¶
¶
Because setting wares is a common task, there is a shortcut by pass
¶
~~~~ ¶
hq:set_wares
log = 10, ¶
planks = 20, ¶
granite = 20, ¶
marble = 5, ¶
}) ¶
~~~~ ¶
¶
Same goes for setting workers: ¶
¶
~~~~ ¶
hq:set_workers
empire_builder = 5, ¶
empire_carpenter = 2, ¶
empire_lumberjack = 5, ¶
}) ¶
~~~~ ¶
¶
Like with the buildings name you will find the right names for wares and workers in the corresponding _'init.lua'_ in the subfolders of _'data/tribes/'_. Add as many wares and workers as you like. After your'e done you should make a test run. ¶
¶
### Create a message box ¶
¶
You may have seen that our scenarios have some message boxes to infrom the player about the story. In the `init.lua` we have included `messages.lua`. This file contains convenient functions for messages. We are using [campaign_message_box()](https://wl.widelands.org/docs/wl/autogen_auxiliary_messages/#campaign_message_box) and add it to the `story_script.lua`: ¶
¶
~~~~ ¶
campaign_message_box({title = "This is the title", body = p("Hi, this is my first scenario")}) ¶
~~~~ ¶