Changes in WikiSandbox
Revision Differences of Revision 89
Test [[ wikisyntax | wiki syntax ]] here :-) ¶¶
[TOC] ¶
¶
Some initial help for creating a scenario, either for creating a complete campaign or as a standalone scneario. If you have reached the end of this tutorial you will have some basic knowledge on how to create a scenario. We can't provide a full explanation of the Lua language, nor all the possibilities of the Lua interface
¶
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, e.g. [notepad++](https://notepad-plus-plus.org), [Geany](https://www.geany.org) or [dig through wikipedia articles about text editors](https://en.wikipedia.org/wiki/Text_editor) ¶
* You may also take a look in the scripting files of the implemented campaigns, which you can find in the data directory of your widelands installation. Look into the folder data/campaigns. This article follows the same structure of filenames. ¶
¶
To follow this example, create an empty map with only one player set at position 0,0 . To find this position watch the values at the bottom right in the editor. This values represents: (x position, y position, height). Make sure you have set the tribe 'Empire' in the menu '
¶
## init.lua ¶
¶
You have read that the file `your_map/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 some helpers ¶
¶
~~~~ ¶
include "scripting/coroutine.lua" ¶
include "scripting/messages.lua" ¶
include "scripting/ui.lua" ¶
include "scripting/richtext.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 corresponding 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 file _'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 (the one you have set) and assign it to the variable 'plr'. If you have set more players to the map, they can be accessed by increasing the value in the brackets, so `.players[2]` is the second player. ¶
* `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
¶
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/
~~~~ ¶
¶
The file _'
¶
##
¶
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. ¶
¶
### 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: ¶
¶
~~~~ ¶
local hq = plr:place_building("empire_headquarters", plr_sf, false, true) ¶
~~~~ ¶
¶
We call the function [place_building()](
¶
The above function returns a reference to the created buildings. In this example this is stored in the __local__ variable `hq`. ¶
¶
__Importand remark about local:__ Whenever you assign variables with values, you should do it this way: `local name_of_variable = value`. The keyword _local_ makes sure that this variable is only valid in this scope (file or function). The only exception: If you really know that you will use this variable elsewhere, you can omit the keyword `local`. But in this case you should give the variable a name which is absolutely clear! ¶
¶
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! If you go through the documentation you may notice that some entries have brackets, and others not. The entries with brackets are functions, other are properties. Examples: ¶
¶
* Properties (can be accessed through a point): [Player.name](https://wl.widelands.org/docs/wl/autogen_wl_game/#wl.game.Player.name) ¶
* Functions (must be called with a colon): [Player:sees_field(f)](https://wl.widelands.org/docs/wl/autogen_wl_game/#wl.game.Player.sees_field) ¶
¶
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. ¶
¶
### Fill buildings ¶
¶
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 local 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 passing a table to set_wares(): ¶
¶
~~~~ ¶
hq:set_wares({ ¶
log = 10, ¶
planks = 20, ¶
granite = 20, ¶
marble = 5, ¶
}) ¶
~~~~ ¶
¶
Same goes for setting workers and soldiers: ¶
¶
~~~~ ¶
hq:set_workers({ ¶
empire_builder = 5, ¶
empire_carpenter = 2, ¶
empire_lumberjack = 5, ¶
}) ¶
¶
hq:set_soldiers({0,0,0,0}, 45) ¶
~~~~ ¶
¶
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 again. ¶
¶
¶
## ma
¶
The
~~~~ ¶
... ¶
incl
~~~~
¶
###
¶
You may have seen that our scenarios have some message boxes to inform the player about the story. In our _'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 new file _'main_thread.lua'_: ¶
¶
~~~~ ¶
campaign_message_box({title = "This is the title", body = p("Hi, this is my first scenario")}) ¶
~~~~ ¶
¶
We give the function a table (enclosed with curly braces {}). The 'body' must be formatted with the richtext system, so we wrap it in a p-tag. See [richtext.lua](https://wl.widelands.org/docs/wl/autogen_auxiliary_richtext/) for further formatting functions. ¶
¶
~~~~ ¶
... ¶
include "map:scripting/starting_conditions.lua" ¶
include "ma
~~~~ ¶
¶
Run a test. ¶
¶
You may have more than one message box in your campaign. For better readability of your main script in _'main_thread.lua'_ it is ususally better to put the table(s) of text in an extra file. The built in campaigns have them usually in a file called _'texts.lua'_ which get included in the [include block of your init.lua](#including-some-helpers) or at the beginning of _'main_thread.lua'_. This will look then like: ¶
¶
File _'texts.lua_': ¶
~~~~ ¶
first_message = { ¶
title = "This is the title", ¶
body = p("Hi, this is my first scenario") ¶
} ¶
~~~~ ¶
¶
File _'main_thread.lua'_: ¶
~~~~ ¶
-- Including tables of text ¶
include "map:scripting/texts.lua" ¶
¶
campaign_message_box(first_message) ¶
~~~~ ¶
¶
The first line in the above example (beginning with two hyphens) is a comment. You should comment your code as mush as possible but not more than needed. When you start this scenario the following will happen: ¶
¶
1. The program looks for a file called _'scripting/init.lua'_ in the map directory. If it is present, load it: ¶
2. Reading _'init.lua'_ from top to bottom. So all functions of included files and global variables are loaded. The last line include our file _'main_thread.lua'_ so this will be read ¶
3. Reading file _'main_thread.lua'_ from top to bottom. Here we include _'texts.lua'_ and all tables will be loaded. Then show the message box. ¶
¶
### Triggering events - adding logic ¶
¶
For now we have some basics, but we need some events to make the campaign alive. Such events are the most important things in campaigns. They offer functionality like: ¶
¶
* Show message boxes when things happens ¶
* Running out of building material ¶
* The player has reached a specific point on the map ¶
* A specific building has been build ¶
* Add objectives a player has to solve ¶
* and so on ¶
¶
Usually an event is combined with an objective, but we leave creating objectives
¶
*
*
¶
Both possibilities needs a field to work with. So the first thing is to get a field. Fields are part of the map and can be accessed through `wl.Game().map`. We have assigned this to the variable `map` in the [global variables section of init.lua](#global-variables). Now we use this variable and call the function [map:get_field(x,y)](https://wl.widelands.org/docs/wl/autogen_wl_map/#wl.map.Map.get_field). This function needs the x and y coordinates of the map, so add the following to _'main_thread-lua'_ below the call to campaign_message_box: ¶
¶
~~~~ ¶
¶
print("Field: ", field , "Owner: ", field.owner) ¶
~~~~ ¶
¶
If you run the scenario the field and the owner of that field will be printed in the console. Note that the print statement is only executed after clicking "OK" in the message box. ¶
¶
What we need further is a mechanism to check if the owner of that field changed. We need a loop that runs the same code over and over until the owner has changed. The problem with such loops is that they can't be run as a standalone loop in lua. This is where coroutines comes in. A coroutine is started with the command [run(function)](https://wl.widelands.org/docs/wl/autogen_auxiliary_coroutine/). The function _run()_ needs a function, so we wrap the loop in a function and call `run()` with the functions name as argument at the end of _'main_thread.lua'_. Replace the previ
¶
~~~~ ¶
function check_field_owner() ¶
local field = map:get_field(10,0) ¶
while true do ¶
print("Field: ", field , "Owner: ", field.owner) ¶
sleep(1000) ¶
end ¶
end ¶
¶
run(check_field_owner) ¶
¶
campaign_message_box(first_message) ¶
~~~~ ¶
¶
Run the scenario. ¶
¶
Now every second the field coordinates and the owner of the field get printed onto the console. The row `sleep(1000)` is __really__ important. If you forget that, this loop prevents every interaction between you and the program itself: ¶
¶
* A player can't do anything else while the loop is executed ¶
* The only way to stop it is to kill the whole program either by clicking on the 'X' of the window, or with your taskmanager ¶
¶
Ok, now it's time for some magic: Run your scenario and explore into the direction of the field (to the right). As soon the field is owned by you, the output will change. Why is this magic? The variable _field_ is defined outside of the loop so it is initialized only once. One could think that the fields state (the owner in this case) is also only initialized once, but this is not the case. That is because the variable _field_ is a __reference__ to the field. Whenever this field owner changes the changes are also reflected in the variable _field_! ¶
¶
~~~~ ¶
function check_field_owner() ¶
local field = map:get_field(10,0) ¶
while field.owner ~= plr do ¶
sleep(1000) ¶
end ¶
campaign_message_box({ title = "Field found", body = p("We have reached the field")}) ¶
end ¶
¶
run(check_field_owner) ¶
~~~~ ¶
¶
The condition `field.owner ~= plr` means: field.owner __not equal__ plr. Such a comparison returns either 'true' or 'false'. See also [Rational Operators](https://www.lua.org/pil/3.2.html) for other types. For other types of loops see [Control structures](https://www.lua.org/pil/4.3.html). ¶
¶
As soon the message box appears, we can be sure that the loop has been ended. Now, as an exercise, try to add a new function plr_sees_field() and use [Player:sees_field()](https://wl.widelands.org/docs/wl/autogen_wl_game/#wl.game.Player.sees_field) for the condition. You have to choose another field though, one which is outside the area the player sees, for testing purposes i have used field 15,10. Move also the table of the message box into the file _'texts.lua'_ and make the corresponding changes. Run the
¶
When running the scenario, you should see at least two message boxes popping up: One after the first loop has ended, and the new one after the second loop has ended. ¶
¶
If you can't get it to work, look in the chapter [Solutions](#solutions). ¶
¶
Note that both loops will end (the message boxes appear) without any delay. That means both functions are running simultaneously. This is the magic of coroutines, when running the functions with the command `run(function)`. The function will be loaded and executed, but the program turns immediately back and executes the additional function of the second call to `run()`. ¶
¶
There is one drawback with coroutines: If you save the game, the coroutines and the state of their variables are saved also. This means you can't run a game, save it, change the logic of a coroutine, and reload the saved game to check the new logic of the coroutine. The new logic will not be part of the loaded save game, because it uses the old logic. The only way to test the new logic is to start a new game. This makes working on scenarios a bit hard, especially for beginners.
¶
###
¶
* scr
* do
* c
¶
### Conclusion ¶
¶
If you have reached this point of this tutorial you have learned a lot. Here are the main things: ¶
¶
* Split logic and texts und leave logic in _'main_thread.lua'_ whereas put texts in other files ¶
* Include each other file either from _'init.lua'_ or at the beginning of _'main_thread.lua'_ ¶
* Use always the keyword `local` when defining variables, except in _'init.lua'_ ¶
* Add events as functions and call them with `run(function)` ¶
* Don't forget to use `sleep()` in loops ¶
* To verify variables you can always add a `print()` statement ¶
* Add events as functions and call them with `run(function)` ¶
¶
## Objectives and objectives.lua ¶
¶
If you have played some of our scenarios you have seen that there are objectives a player has to fulfill. Let's add an objective and also some other stuff: ¶
¶
1. If the field is seen by the player, scroll automatically to that field ¶
2. Show a message box to the player ¶
3. If the player clicks ok in the message box, scroll back to the previous location ¶
4. Add an objective saying that he should build a forester, a woodcutter and produce at least 5 logs ¶
5. Show a message box if the objective is done ¶
¶
The related function to get wares in stock is: [Player:get_wares()](https://wl.widelands.org/docs/wl/autogen_wl_bases/#wl.bases.PlayerBase.get_wares). But for now we implement the automatic scrolling. The used functions are part of [ui.lua](https://wl.widelands.org/docs/wl/autogen_auxiliary_ui/#ui-lua) which we have [included in ini.lua](#including-some-helpers) and are called _scroll_to_field()_ and _scroll_to_map_pixel()_. _scroll_to_field()_ returns the center pixels of the current view. We store this in the local variable `scroll_field` and use this variable to give it _scroll_to_map_pixel()_ later on: ¶
¶
~~~~ ¶
function check_field() ¶
local field = map:get_field(15,0) ¶
while not plr:sees_field(field) do ¶
sleep(1000) ¶
end ¶
local scroll_field = scroll_to_field(field) ¶
campaign_message_box(field_reached) ¶
scroll_to_map_pixel(scroll_field) ¶
end ¶
~~~~ ¶
¶
## Solutions ¶
¶
### Add another function ¶
¶
Does your solution look like this one? ¶
~~~~ ¶
-- Added function to check sees_field() ¶
function check_sees_field() ¶
local field = map:get_field(15,0) ¶
while plr:sees_field(field) ~= true do -- See below ¶
sleep(1000) ¶
end ¶
campaign_message_box(plr_sees_field) ¶
end ¶
¶
run(check_field) ¶
-- Additional run() command ¶
run(check_sees_field) ¶
~~~~ ¶
¶
The condition for the loop could also be written this way to improve readability: ¶
~~~~ ¶
while not plr:sees_field(field) do ¶
~~~~ ¶
¶
## Tips for testing coroutines ¶
¶
* scriptconsole F6 ¶
* dofile("filename") ¶
* commenting coroutines ¶