For your comfort can be all commands and conditions formulated in simple bare sentences. This is called DSL - Domain Specific Language. These senetences are translated into Drools and Java commands.

The rule package consists of two parts: head and rules. In the head there are four important objects

The second part contains the rules. All of these have the form:

rule "unique rule name"
    modifiers

    when
    conditions
    then
    commands
end
                

Every 100 miliseconds are these rules tested; if are the conditions in LHS (left-hand section, the part of the rule between when and then keywords) for some rule satisfied the rule is going to be fired. This means that the commands in the RHS (right-hand section, the part of the rule between then and end keywords) are executed. The commands could change the situation and another rule can be fired. In one moment can the conditions of multiple rules be satisfied - all of them are fired then.

The LHS can contain multiple conditions, each condition on single row. The default meaning of this that all of the conditions must be satisfied at one moment to fire the rule. There is a default and relation between them. There is also a way how to say that only one condition from some of them must be satisfied. This is the or relation. You can write it this way:

when
    condition 1
    or
    condition 2

then
                

If you want to write more complex LHS, use parentheses:

when
    condition 1
    (condition 2
    or
    condition 3)
    condition 4
then
                

This means that the both condition 1 and condition 4 must be satisfied and also either condition 2 or condition 3 (or both of them). The order of conditions is not vital but it affects the performance. You should put the more computionaly difficult conditions on the bottom and the bottleneck conditions on the top. If you do not know which order is better, do not care.

See documentaion for the complete list of currently supported conditions.

Unlike in the LHS, the order of commands in RHS is very important. Each command must be written in a single row and these are executed in a top-down order. The complete list of currently supported commands is in documentation.

Modifiers alter the way how the rules are executed. For the complete list look into the Drools documentation but for you can be important these two:

If you want to write your own comments (what is strongly recommended) or remove some condition or command for debugging purposes (you want to add it again in the future), start the line with sharp character #. Everything between the sharp and the end of line is considered as comment and Drools ignore it.

For debugging purposes we put some "log" commands into the rules. These have no impact on the scenario but we will see its proceeding.

Let us look on the MyRulesFile.dslr:

package com.example.myscenario

import cz.cuni.amis.pogamut.edu.Scenario.State;
import cz.cuni.amis.pogamut.edu.controlserver.KeyEvent.Event;

global cz.cuni.amis.pogamut.edu.ut2004.UT2004Scenario scenario

expander edu-english.dsl
                

From your point of view there is nothing interesting here. This part will me always the same, only the package name will change. The actual action of the scenario is described below:

rule "Scenario start"
    when
        scenario is ready
    then 
        log "Starting the scenario"
        start scenario
        transport player "Player1" to "point A"
        enable current position on map
        perform act "going to B"		
end

rule "Arrival to B"
    when
        performing act "going to B"
        player is nearby "point B"
    then 
        log "Arrived to B"
        show message "You have arrived to poing B" for 10 seconds
        perform act "showing dialog"
        # begin of the definition of the dialog
        create dialog "myDialog"
        create option list "options"
        add "options" to dialog "my dialog"
        add new option "Option A" to "options" as "1"
        add new option "Option B" to "options" as "2"
        add new option "Option C" to "options" as "3"
        create submit button "submit"
        set size of "options" to 0.9, 0.7
        set position of "options" to 0.05, 0.1		
        set text on "submit" to "Submit"
        set size of "submit" to 0.4, 0.1
        set position of "submit" to 0.3, 0.8
        add "submit" to dialog "my dialog"
        # end of dialog
        show dialog "in shop"
end

rule "Dialog returned 1"
    when
        performing act "showing dialog"
        dialog "myDialog" returned in "options" value "1"
    then
        log "option A"
        show message "You have selected option A" for 10 seconds
        perform act "going to C"
end

rule "Dialog returned 2 or 3"
    when
        performing act "showing dialog"
        (dialog "myDialog" returned in "options" value "2"
            or
         dialog "myDialog" returned in "options" value "3")
    then
        log "option B or C"
        show message "You have selected option B or C" for 10 seconds
        perform act "going to C"
end

rule "Arrival to C"
    when
        performing act "going to C"
        player is nearby "point C"
    then 
        log "Arrived to C"
        show message "You have succesfully finished the scenario"
        finish scenario
end

                

This is the description of the scenario. Although the definition of the dialog looks awfully, there is nothing difficult about that. There is a main dialog with two elements: option list "options" and submit button. The option list contains three options with their particular values. All the other commands specify the shape and positioning of the two mentioned elements. That is all.

We have not covered two events: when the player wants to display or hide the map and when he enters the restricted area. The first one would look as this:

rule "Map showing"
    when
        user pressed "M" key
        map is hidden
    then
        set keypress "M" processed
        show map
end

rule "Map hiding"
    when
        user pressed "M" key
        map is shown
    then
        set keypress "M" processed
        hide map
end     
                

Unfortunately you have to manually discard the keypresses - if you would not do that, the second condition would fire (and hide/show the dialog again) causing an infinite loop of showing and hiding. The automatic discard of the keypress would not be wise in case that two rules would be waiting for the keypress.

Thanks to the map files (we will show how to make them in the next section) is the intrusion into the restricted area very simple to intercept - we need only single simple rule:

rule "Restricted area"
    when
        player is in area "restricted"
    then
        log "Entered restricted"
        show message "You have entered the restricted area! You have failed the scenario."
        finish scenario
end     
                

Voila, all rules for your scenario are completed.

It would be very uncomfortable to use commands as "if the player is in rectangle specified by coordinates 324, 5654, 756, 6544" and such. That is why all these coordinates are stored in a file called map file. More accurately, there can be more of such files but the information from them are merged during the loading.

The parts of space are called areas. There are two basic types of them: simple areas and complex areas. The simple areas are rectangles, circles and polygons and you usually do not assign a name (ID) to them. The complex areas do not have coordinates - they are specified by their subareas. These subareas can be also complex areas or simple ones. They form a tree-like structure: simple areas form streets, squares, parks and such, these form districts and districts form a city. This partitioning is up to you - nothing forces to have three levels, you can have two or fifty of them.

Sometimes you would like to have some point marked on the map or refer to the point in the scenario. These are called POIs - points of interest. You can also set their symbol, color and description.

Similar to marks are paths. These are broken lines displayed in the map. You can set their color and width. Unlike the POIs you cannot refer to them in rules because they have not a single position.

You do not have to edit the map manually, there is an editor provided, of course.

ES provides a wizard to easy map file creation. Right-click on the folder where you want to create the map file and select New -> Other.... In the dialog select Educational Scenarios Map from the Educational Scenarios folder and press the Next button.

Fill in the new name of the map file with .xml extension (e.g. map.xml ) and press Next button again.

Select the initial content. The entries have following meaning:

Press the Finish button when all the data are filled.

Now should your new map file appear in the package tree view

After you have created the map file the editor should automatically open. The screen will look as this:

If you close the editor you can open it again by right-clicking on the file and selecting Open With -> EduMap editor as you can see on the image below. Double-clicking should do the same job when you try to open it for the second time.