Advanced World Creation

Namespace: RUR

RUR

The namespace reserved for all the Reeborg World methods. All the method documented here must be prefixed by RUR.

When a name must be specified, and your language is set to something else than English (currently only French is fully supported; and Korean is mostly supported for object names), you should specify the French (or Korean) name. Internally, the names are converted into English and missing translations are ignored so you might get away with using English names.

To see what name to use, execute RUR.show_all_things() and see if a translated name exists for the language Reeborg's World is currently using.

Si vous utilisez l'interface française, il est recommandé de spécifier le nom des "choses" en français.

Source:

Classes

Deque
Graph
PriorityQueue

Methods

add_background_path(name, path)

This function sets a named tile as background for a path

Parameters:
Name Type Description
name string

The name of a tile or a colour recognized by JS/HTML. No check is performed to ensure that the value given is valid; it the tile name is not recognized, it is assumed to be a colour. If a new tile is set at that location, it replaces the pre-existing one.
path array

A Javascript Array (or Python list) whose items are arrays of the form [x, y].
Source:

add_background_tile(name, x, y)

This function sets a named tile as background at a location.

Parameters:
Name Type Description
name string

The name of a tile. Any pre-existing tile or color at that location will be replaced by the new value.
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

  • Will throw an error if (x, y) is not a valid location.

  • Will throw an error if name is not a known thing.

add_bridge(name, x, y)

This function sets a named "thing" as a bridge at that location. There can be only one bridge at a given location.

Parameters:
Name Type Description
name string

The name of a bridge.
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

  • Will throw an error if (x, y) is not a valid location.

  • Will throw an error if name is not a known thing.

  • Will throw an error if there is already a bridge at that location, unless this is done from code in the Onload editor in which case the new bridge replaces the old one and a message is written to the browser's console.

add_colored_tile(color, x, y)

This function sets a uniform color as background at a location. Any pre-existing tile or color at that location will be replaced by the new value.

Parameters:
Name Type Description
color string

A colour recognized by JS/HTML. No check is performed to ensure that the value given is a valid color recognized by JS/HTML (see example below), except that the color specified cannot be a known "thing", which is the opposite of RUR.add_background_tile.
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

Will throw an error if (x, y) is not a valid location.

Example
// Show how to set a color
World("Alone")
RUR.add_colored_tile("blue", 1, 8)
RUR.add_colored_tile("#00ff00", 3, 8)
RUR.add_colored_tile("rgb(255, 0, 0)", 5, 8)
RUR.add_colored_tile("rgba(255, 0, 0, 0.1)", 7, 8)
RUR.add_colored_tile("hsl(24, 71%, 77%)", 9, 8)

add_decorative_object(name, x, y)

This function adds a decorative object at a specified location.

Parameters:
Name Type Description
name string

The name of an object or a colour recognized by JS/HTML. No check is performed to ensure that the value given is valid; it the name is not recognized, it is assumed to be a colour. There can be more than one type of decorative object at a given location. If a decorative object with name "A" is already at a given location and this function is called to add another, a message is logged to the console and nothing further is done.
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

Will throw an error if (x, y) is not a valid location.

add_final_position(name, x, y)

This function adds a final position as a goal for the default robot. It is possible to call this function multiple times, with different x, y positions; doing so will result in a final position chosen randomly (among the choices recorded) each time a program is run.

If x, y had previously been set as a goal final position no change is being made and a message is logged in the browser's console.

Parameters:
Name Type Description
name string

The name of the object/image we wish to use to represent the final position of the robot. Only one image can be used for a given world, even if many possible choices exist for the final position: each time this function is called, the name argument replaces any such argument that was previously recorded.
x integer

The position on the grid
y integer

The position on the grid
Source:
Throws:

  • Will throw an error if the final position is not valid [not implemented yet]

  • will throw an error if the name is not recognized [not implemented yet]

add_initial_position(x, y)

This function adds an initial (starting) position as a possibility for the default robot. It is possible to call this function multiple times, with different x, y positions; doing so will result in a initial position chosen randomly (among the choices recorded) each time a program is run.

If x, y had previously been set as an initial position no change is being made and a message is logged in the browser's console.

Parameters:
Name Type Description
x integer

The position on the grid
y integer

The position on the grid
Source:
Throws:

  • Will throw an error if the the world does not contain a robot

  • Will throw an error if the initial position is not valid [not implemented yet]

add_new_thing(thing)

This method makes it possible to add new "things", represented by an image.

If the name of an existing thing is specified with different properties, it is replaced by the new one.

Important Other than for testing purposes, This method should only be called from the "Onload" editor so that it can start fetching the required images as soon as possible, and try to ensure that the images will be ready to be shown when a program is executed.

Parameters:
Name Type Description
thing Object

A Javascript object (similar to a Python dict) that describes the properties of the "thing".

Properties
Name Type Argument Description
name string

The name to be given to the "thing"; an exception will be raisd if it is missing.
info string <optional>

Some information to be displayed about this "thing" when a user clicks on "World Info" and then on this thing on the world canvas. It is highly recommended to include this.
color string <optional>

A string representing a valid html color (named, rgb, rgba, hsl or #-notation). Either thing.color, thing.urlorthing.images` must be specified.
url string <optional>

If a single image is used, this indicated the source. Either thing.color, thing.url or thing.images must be specified.
images Array.<strings> <optional>

If multiple images are used (for animated "things"), this array (list) contains the various URLs. Either thing.color, thing.url or thing.images must be specified.
selection_method string <optional>

For animated "things"; choose one of

  • "sync",
  • "ordered",
  • "random",
  • "cycle stay" or

  • "cycle remove".

    If the selection method is not recognized, "random" will be used, and no error will be thrown.
goal object <optional>

If the "things" can be used for an object that can be picked up or put down by Reeborg, includes thing.goal to describe the image(s), following the same pattern as above (thing.goal.url, thing.goal.images, thing.goal.selection_method), except that goal is ignored if color is true.
fatal string <optional>

Program ends if Reeborg steps on such a "thing" with a value that is equivalent to "true" when used as background things or obstacles, unless a bridge offering the adequate protection is present or an object carried by Reeborg has the right protection defined. This value is usually set to the name of the "things" so as to facilitate defining objects or bridges which offer the right protection. For fatal things, message should be defined as well.
message string <optional>

The message shown when Reeborg steps on a fatal tile.
detectable string <optional>

If thing.fatal and thing.detectable are both equivalent to "true", Reeborg can detect this "thing" with front_is_clear() and right_is_clear() if it is set as an obstacle or a background thing.
protections Array.<strings> <optional>

Indicates against which fatal thing this offer protection. Protection is given when things are used as a bridge or when they are carried.
solid boolean <optional>

If sets to True, prevents a pushable object from sliding onto this "things" when used as a background thing or as an obstacle.
x_offset integer <optional>

By default, "things" are drawn on a set grid. Specifying a value for x_offset result in the "things" drawn off grid, by a number of pixel equal to x_offset. This is only valid for images - not for colors.
y_offset integer <optional>

By default, "things" are drawn on a set grid. Specifying a value for y_offset result in the "thing" drawn off grid, by a number of pixel equal to y_offset. This is only valid for images - not for colors.
transform object <optional>

See the book Reeborg's World: a Teacher's guide for an explanation.
Source:
Throws:

  • Will throw an error if name attribute is not specified.

  • Will throw an error if no image is supplied (either via the url or the images attribute) and color does not evaluate to true.

add_object(name, x, y [, options])

This function adds one or more of a given object at a location.

Parameters:
Name Type Argument Description
name string

Name of the object
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
options object <optional>

A Javascript object (or Python dict) containing additional arguments

Properties
Name Type Argument Description
goal boolean <optional>

If true, this will represent a goal i.e. the number of object that must be put at that location.
number integer <optional>

The number of objects to add at that location; it is 1 by default.
replace boolean <optional>

If true, the specified number (default=1) will replace the existing number of objects at that location. During the Onload phase, this is automatically set to true.
min integer <optional>

Specifies the minimum of objects to be put at that location; together with options.max, it is used to choose a random number of objects to be found at that location.
max integer <optional>

Specifies the maximum number of objects to be put at that location; together with options.min, it is used to choose a random number of objects to be found at that location.
Source:
Throws:

  • Will throw an error if (x, y) is not a valid location.

  • Will throw an error if name is not a known thing.

add_obstacle(name, x, y)

This function sets a named "thing" as an obstacle at that location

Parameters:
Name Type Description
name string

The name of a the "thing" representing the obstacle.
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

  • Will throw an error if (x, y) is not a valid location.

  • Will throw an error if name is not a known thing.

  • Will throw an error if there is already such a named obstacle at that location, unless this is done from code in the Onload editor in which case the a message is written to the browser's console and the request is ignored.

add_pushable(name, x, y)

This function adds a named pushable at a location; there can only be one pushable object at a given location.

Parameters:
Name Type Argument Description
name string

The name of a the "thing" representing the pushable.
x integer

Position: 1 <= x <= max_x
y integer

Position: `1 <= y <= max_y
options.goal boolean <optional>

Indicate if this is to be set as a goal
Source:
Throws:

  • Will throw an error if (x, y) is not a valid location.

  • Will throw an error if name is not a known thing.

  • Will throw an error if there is already a pushable object at that location, unless this is done from code in the Onload editor in which case the new pushable object replaces the old one and a message is written to the browser's console.

add_wall(orientation, x, y)

This function adds a wall at the stated stated position and orientation if there is none already located there; otherwise, it raises an exception, except if this is done in the Onload phase in which case it simply logs in an exception.

Parameters:
Name Type Argument Description
orientation string

One of "east", "west", "north", "south".
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
options.goal bool <optional>

If true, get information about goal walls.
Source:
Throws:

  • Will throw an error if x or y is outside the world boundary.

  • Will throw an error if orientation is not a valid choice.

  • Will throw an error if there is already a wall there, except if this is done in the Onload phase in which case it simply logs in an exception.

animate_robot(models, robot_body)

Robot animation is done by cycling through a list of robot models, each model having 4 images (one for each orientation).

Parameters:
Name Type Description
models array

A list of robot models. If the list contains a single model, the animation is stopped.
robot_body object

A robot_body object.
Source:

check_path(desired_path [, options])

This function compares the path followed by the default robot with that which was desired.

Parameters:
Name Type Argument Description
desired_path list

A desired path, as printed by RUR.print_path.
options Object <optional>

A Javascript object (similar to a Python dict).

Properties
Name Type Argument Description
failure string <optional>

If the followed path was not the specified one and options.failure is specified, an exception will be raised and options.failure will be shown.
success string <optional>

If the followed path was the specified one and options.success is specified, an exception will be raised and options.success will be shown.
show_path string <optional>

If the followed path was not the specified one and options.show_path is set to true, the desired_path will be shown. If this is desired, we suggest to use the string "true" which will be valid in both Python and Javascript. If the correct path is followed, and you wish to show the desired_path, simply call RUR.show_path() explicitly with the relevant arguments prior to calling RUR.check_path().
color string <optional>

If the desired path is shown and options.color is specified, it will be the color used to show the path.
Source:
Returns:

True if the correct path was followed, false otherwise and if the relevant option options.success or options.failure is not specified.

Type
bool

clear_background()

This function removes all existing background tiles

Source:

configure_red_green(red, green)

Colour blind users may use this function to choose two colours, instead of red and green, to indicate if the number of objects required as a goal at a given location has been achieved or not. The choices made are saved in the browser's local storage and should only need to be entered once.

Parameters:
Name Type Description
red string

A colour indicated either as a named colour, like "red", "indigo", etc., an rgb value like "rgb(125, 34, 22)", or an rgba value, or a hexadecimal colour like "#FA2336".
green string

Another colour, seen as contrasting with red by the user.
Source:

create_maze(max_x, max_y [, options])

Creates a maze of a specified size. This is done with a depth-search wall removal algorithm.

Note: When options.recording is set to true, the number of steps required to build and show the maze is max_x * max_y + 3; if required, use set_max_nb_steps() to increase the default limit of 1000.

For the palette: any color value recognized by html/javascript (i.e. red, rgb(126, 230, 0), #ffc356, etc., can be used).

Parameters:
Name Type Argument Description
max_x integer

The width of the world.
max_y integer

The height of the world.
options object <optional>
Properties
Name Type Argument Description
small_tiles bool <optional>

Indicates if small tiles must be used. This is useful for larger mazes
recording bool <optional>

If true, the walls being removed will be shown as they are removed one by one, in a series of frames. This is only useful for demonstration, and will only visible if the maze is created as part of the Pre code or the main code - but not in the Onload phase.
use_colors bool <optional>

If true, the path construction will be shown using a pre-defined color scheme, indicating the starting point, and the branching points.
visible_grid bool <optional>

If true, the grid will be (possibly more) visible. This is equivalent to writing RUR.state.visible_grid = true in your program. This might be useful if you have options.use_colors == true and choose a custom palette with opaque colors.
palette obj <optional>

An optional color palette. You can replace any or all of the default colors.
palette['start'] string <optional>

Color to use as starting point.
palette['end'] string <optional>

Color used to indicate that we have reached a dead end.
palette['two way'] string <optional>

Color to use in "corridors".
palette['three way'] string <optional>

Color to use in simple junctions.
palette['four way'] string <optional>

This happens relatively rarely: it correspond to a grid square not in a room but open on all sides.
Source:

delete_maze_info()

Selectively delete maze info. If not argument is included, the entire maze information is deleted from the world definition.

Source:

fill_background(name)

This function sets a named tile as background for the entire world

Parameters:
Name Type Description
name string

The name of a tile or a colour recognized by JS/HTML. No check is performed to ensure that the value given is valid; it the tile name is not recognized, it is assumed to be a colour. If a new tile is set at that location, it replaces the pre-existing one.
Source:

fill_walls()

Fills the entire world with walls.

Source:

get_background_tile(x, y)

This function gets the tile name found at given location. Note that this could be an HTML colour. If nothing is found at that location, null is returned (which is converted to None in Python programs.) Important RUR.get_background_tile uses the singular form, instead of the plural (i.e. tile instead of tiles) since there only one tile can be found at a given location.

Parameters:
Name Type Description
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

Will throw an error if (x, y) is not a valid location.

Returns:

The name of the tile found at that location or null/None.

Type
string

get_bridge(x, y)

This function gets the name of the bridge name found at given location. If nothing is found at that location, null is returned (which is converted to None in Python programs.)

Parameters:
Name Type Description
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

Will throw an error if (x, y) is not a valid location.

get_bridge_protections(x, y)

This function returns an array of "protections" given by a bridge at that location. If no bridge is found, or if a bridge is found but offer no protection, an empty array is returned.

Parameters:
Name Type Description
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

Will throw an error if (x, y) is not a valid location.

Returns:

An array of strings, each string being a protection against a specific type of fatality; this could be an empty array.

Type
Array

get_decorative_objects(x, y)

This function returns a list/array of the decorative objects found at a given position. If nothing is found at that location, an empty array is returned.

Parameters:
Name Type Description
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

Will throw an error if (x, y) is not a valid location.

Returns:

An array containing the name of the decorative objects found at that location

get_editor_from_world()

A world can be saved with the content shown in the main code editor at the time; the person loading the world usually does not see this content since what is shown in the main editor is their own code. However, this content can be retrieved by calling this function. Its only use case is to set the content of the extra editor/module.

Source:
Example
RUR.set_extra_content(RUR.get_editor_from_world())

get_library_from_world()

A world can be saved with the content shown in the library tab at the time; the person loading the world usually does not see this content since what is shown in the library is their own code. However, this content can be retrieved by calling this function. Its only use case is to set the content of the extra editor/module.

Source:
Example
RUR.set_extra_content(RUR.get_library_from_world())

get_objects(x, y [, options])

This function returns a Javascript Object containing the names of the objects found at that location. When using from Python, it should be explictly converted into a dict using dict(RUR.get_objects(x, y)).

If nothing is found at that location, null is returned (which is converted to None in Python programs.)

Parameters:
Name Type Argument Description
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
options object <optional>

A Javascript object (or Python dict) containing additional arguments

Properties
Name Type Argument Description
goal boolean <optional>

If true, this will represent a goal i.e. the number of object that must be put at that location.
Source:
Throws:

Will throw an error if (x, y) is not a valid location.

get_obstacles(x, y)

This function gets the obstacles at given location and return their names in an array/list.

Parameters:
Name Type Description
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

Will throw an error if (x, y) is not a valid location.

Returns:

A list of strings representing the name of the obstacles.

Type
list

get_position_in_front(robot_body)

IMPORTANT This function should only be used for the advanced frame insertion technique; in normal programs, used position_in_front(). Use import reeborg_en followed by help(reeborg_en.position_in_front()) for details about the return values which are different from those of RUR.get_position_in_front().

Parameters:
Name Type Description
robot_body object

A robot body object, having the proper attribute for position (x, y coordinates) and orientation. Note that you should pass in a robot body object obtained from some other function such as RUR.get_robot_body_by_id(), since the internal names for the various attributes are subject to change.
Source:
Returns:

An object of the form {x:x_value, y:y_value} wherex_valueandy_valueare integers and represent the position in front of the robot. If the position is not within the world boundaries, the object{x:0, y:0}` is returned.

Type
object

get_print()

This function returns the content of the standard output, produced by print in Python, and either write or writeln in Javascript.

Source:
Returns:

The content of the print output.

Type
string

get_property(name, property)

This method returns the value of a given property for a "thing". Important: the returned value will be the English default even if a translation exists and might appear in other contexts, like the "World Info".

If the property is undefined, null will be returned (which will be converted to None if Python is used).

Parameters:
Name Type Description
name string

The name of the "thing".
property string

See the examples
Source:
Examples
print(RUR.get_property("water", "info"))  # Python
write(RUR.get_property("water", "fatal"))  // Javascript

get_protections(robot_body)

This return a list of protections carried by the robot against named fatalities.

Parameters:
Name Type Description
robot_body object

robot body object
Source:
Returns:

an array of protections;

get_pushable(x, y)

This function returns the name of a pushable found at that location; If nothing is found at that location,null is returned (which is converted to None in Python programs.)

Parameters:
Name Type Argument Description
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
options.goal boolean <optional>

Indicate if this was set as a goal
Source:
Throws:

Will throw an error if (x, y) is not a valid location.

Returns:

The name of the pushable at that location, or null.

Type
string

get_robot_body_by_id(id)

IMPORTANT This function should only be used for the advanced frame insertion technique.

This function indicates returns a robot "body" specified by its id, if a robot with such an id exists. (The id is like a serial number: it is a number unique for each robot created). No error checking is performed on the argument. If some exception is raised, it is simply logged in the browser's console.

Important: This function cannot be used directly in a Python program to yield something sensible. (If you want, you can convert the result to a Python dict() -- provided it is not None, of course.) From Python, use instead get_robot_by_id() (without the RUR prefix), or robot_spécifique in French, which returns a true Python UsedRobot instance.

Parameters:
Name Type Description
id integer
Source:
Returns:

the body of the robot as a Javascript object, null if a robot with this id cannot be found.

Type
object

get_robot_by_id(id)

IMPORTANT This function should only be used for the advanced frame insertion technique. This function indicates returns a Javascript UsedRobot instance specified by its id, if a robot with such an id exists. (The id is like a serial number: it is a number unique for each robot created). No error checking is performed on the argument. If some exception is raised, it is simply logged in the browser's console.

Important: This function cannot be used directly in a Python program to yield something sensible. From Python, use instead get_robot_by_id() (without the RUR prefix), or robot_spécifique in French, which returns a true Python UsedRobot instance.

Parameters:
Name Type Description
id integer
Source:
Returns:

A Javascript UsedRobot instance corresponding to the robot with the specified id, or null if a robot with this id cannot be found.

Type
object

get_robot_location(robot_body)

IMPORTANT This function should only be used for the advanced frame insertion technique; in normal programs, used position_here(). Use import reeborg_en followed by help(reeborg_en.position_here()) for details about the return values which are different from those of RUR.get_robot_location().

This function returns the location of a robot (position and orientation).

Parameters:
Name Type Description
robot_body object

A robot body object, having the proper attribute for position (x, y coordinates) and orientation. Note that you should pass in a robot body object obtained from some other function, such as RUR.get_robot_body_by_id(), since the internal names for the various attributes are subject to change.
Source:
Returns:

An object of the form {x:x_value, y:y_value, orientation:orientation_value} wherex_valueandy_valueare integers andorientation_valueis one of"east","west","north","south"`.

Type
object

get_walls(x, y)

This function returns a list of walls at a location from within the boundaries of a normal (rectangular) world. The order in which they are listed, if present, is "east", "north", "west", "south".

Parameters:
Name Type Argument Description
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
options.goal bool <optional>

If true, list the goal walls found at that position instead of regular walls.
Source:
Throws:

Will throw an error if x or y is outside the world boundary.

give_object_to_robot(obj, nb [, robot_body])

Give a specified number of object to a robot (body). If the robot, is not specified, the default robot is used.

Parameters:
Name Type Argument Description
obj string

The name of the object type ; e.g. "token"
nb integer

Number of objects at that location; a value of zero is used to remove objects.
robot_body robot.body <optional>
Source:

has_property(name, property)

This method returns "true" if a "thing" has the stated property, and "false" otherwise

Parameters:
Name Type Description
name string

The name of the "thing".
property string
Source:
Examples
# Python example
print(RUR.has_property("water", "fatal"))
// Javascript example
write(RUR.has_property("water", "fatal"))

in_room()

This is meant to be used with mazes. Given an array of rooms, which for a maze is maze.rooms, this function returns true if the point (x, y) is within one of the rooms, and false otherwise.

Source:

is_background_tile(name, x, y)

Use to find out if there is a tile (including color) with that name at a given location.

Parameters:
Name Type Description
name string

The name of the tile; it could be a color.
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Returns:

true/True if there is such a named tile at that location, false/False otherwise.

Example
# A very different solution ...
World("worlds/examples/simple_path.json", "simple_path")
while not at_goal():
    x, y = position_in_front()
    if RUR.is_background_tile("gravel", x, y):
        move()
    else:
        turn_left()

is_bridge(name, x, y)

This function returns true/True if a named bridge is present at a given location, false/False otherwise

Parameters:
Name Type Description
name string

The name of the bridge
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

Will throw an error if (x, y) is not a valid location.

is_decorative_object(name, x, y)

This function returns true/True if a named decorative object is found at that location, false/False otherwise.

Parameters:
Name Type Description
name string

Name of the object
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

Will throw an error if (x, y) is not a valid location.

is_detectable_position(x, y)

For Reeborg to determine if a fatal "thing" is present (e.g., for front_is_clear() to returnfalse/False), the "thing" must have adetectableattribute which evaluates totrue/True. This function returnstrue/True` if there is as least such a detectable "thing" at that position.

Parameters:
Name Type Description
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Returns:

true if this position is detectable by the robot, false otherwise

is_fatal_position(x, y, robot_body)

Indicates if the position would be fatal for the robot. A robot can carry protections against fatalities

Parameters:
Name Type Description
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
robot_body object

robot body object
Source:
Returns:

The message of the first fatal thing found [for which the robot has no protection]; if no such thing is found, false/False is returned.

is_object(name, x, y [, options])

This function returns true/True if a named obstacle is present at a given location, false/False otherwise

Parameters:
Name Type Argument Description
name string

The name of the obstacle
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
options object <optional>

A Javascript object (or Python dict) containing additional arguments

Properties
Name Type Argument Description
goal boolean <optional>

If true, this will represent a goal [i.e., the number of object that must be put at that location.]
Source:
Throws:

Will throw an error if (x, y) is not a valid location.

is_obstacle(name, x, y)

This function returns true/True if a named obstacle is present at a given location, false/False otherwise

Parameters:
Name Type Description
name string

The name of the obstacle
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

Will throw an error if (x, y) is not a valid location.

is_pushable(x, y)

This function returns true/True if such a named pushable (possibly a goal) is at that location, false/False otherwise.

Parameters:
Name Type Argument Description
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
options.goal boolean <optional>

Indicate if we want a pushable goal
Source:
Throws:

  • Will throw an error if (x, y) is not a valid location.

  • Will throw an error if name is not a known thing.

Returns:

The name of the pushable at that location, or null.

Type
string

is_robot(x, y)

This function indicates if at least one robot is found at the specified location, false otherwise. No error checking is performed on the arguments. If some exception is raised, it is simply logged in the browser's console.

Parameters:
Name Type Description
x integer

Position
y integer

Position
Source:
Returns:

True if a robot is found at that position, false otherwise.

Type
bool

is_solid_obstacle(x, y)

This function returns true/True if a solid obstacle is present at a given location, false/False otherwise

Parameters:
Name Type Description
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

Will throw an error if (x, y) is not a valid location.

is_valid_position(x, y)

This function indicates if the position is within the world's boundaries.

Parameters:
Name Type Description
x integer

Position
y integer

Position
Source:
Returns:

true/True if the position is within the world's boundaries, false/False otherwise.

Type
bool

is_wall(orientation, x, y)

This function returns true/True if a wall is found at the stated position and orientation, and false/False otherwise.

Parameters:
Name Type Argument Description
orientation string

One of "east", "west", "north", "south".
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
options.goal bool <optional>

If true/True, get information about goal walls instead of regular walls.
Source:
Throws:

  • Will throw an error if x or y is outside the world boundary.

  • Will throw an error if orientation is not a valid choice.

new_robot_images(images)

Create new images for the robot.

Suggestion: use in the Onload editor, so that images can be fetched as soon as the world is loaded.

Python: You can use new_robot_images without the RUR prefix. For the French version, you can use nouvelles_images_de_robot. However, the function described here is preferable as it can be used with either Javascript or Python.

Parameters:
Name Type Description
images Object

A Javascript object (similar to a Python dict) that holds the relevant attributes.

Properties
Name Type Argument Description
model string <optional>

The model name of the robot. Integer values will be accepted as well except for -1 which will raise an error. If the model is not specified, the value "anonymous" will be used.
east string <optional>

A url for the source of the image to be used for the robot in the East orientation. If it is not specified, the default "classic" image will be used.
north string <optional>

Similar to images.east.
west string <optional>

Similar to images.east.
south string <optional>

Similar to images.east.
Source:

onload_set_programming_language(language)

This function must ONLY be called from the Onload editor. It is used to set which of two programming languages are allowed. If the programming mode is compatible with that language, then it is not changed; otherwise, it is change to the default mode (with Code editor) for that language.

This should only be required if the world contains some content to be run (either in the editor, or in the pre- or post- code editors.) Otherwise, do not use so that the world can be used using either programming language.

Parameters:
Name Type Description
language string

Either "python" or "javascript". If the language is not recognized, it is set to "python".
Source:
See:
Example
# Execute the following and, after the world has loaded,
# click on **World Info** to see how this code is used.
World("worlds/examples/simple_path_explained.json")

onload_set_programming_mode(mode)

This function must ONLY be called from the Onload editor. It is used to specify which of five modes must be used for a given world.

This should only be required if the world contains some content to be run (either as blocks, in the editor, or in the pre- or post- code editors) which does require a specific mode. Otherwise, do not use so that the world can be used using all possible programming modes.

Parameters:
Name Type Description
mode string

One of ["python", "javascript", "py-repl", "blockly-js", "blockly-py"]. If the mode is not a recognized value, it will be set to "python".
Source:
Example
// shows how to switch mode to Blockly, where some blocks are already placed.
World("/worlds/examples/square_blockly.json", "Square")

Prints a formatted version of the current maze info if a maze exists.

Source:

This function prints the path followed by the default robot, where the values ['x', 'y'] are used to draw the trace on the screen. Values are only appended to the path when they change; thus, turns and other actions performed at a given location are ignored. The initial position is considered to be part of the path.

Source:

Prints a formatted version of the world map. For Python, use SatelliteInfo.print_world_map() instead.

Source:

randint( [integer] [, integer])

Like the Python function random.randit, it returns a random integer in range [min, max], including both end points.

Parameters:
Name Type Argument Description
integer <optional>

min
integer <optional>

max
Source:

remove_background_tile(name, x, y)

This function removes a background tile (or a colored tile) at a location.

Parameters:
Name Type Description
name string

Name of the tile or colored tile
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

  • Will throw an error if (x, y) is not a valid location.

  • Will throw an error if there is no background tile to remove at that location

remove_bridge(name, x, y)

This function removes a bridge at a location.

Parameters:
Name Type Description
name string

The name of a the "thing" used as a bridge.
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

  • Will throw an error if (x, y) is not a valid location.

  • Will throw an error if there is no such named bridge to remove at that location

remove_decorative_object(name, x, y)

This function removes a decorative object at a location.

Parameters:
Name Type Description
name string

Name of the object
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

  • Will throw an error if (x, y) is not a valid location.

  • Will throw an error if there is no such decorative object to remove at that location

remove_initial_position(x, y)

This function removes an initial (starting) position as a possibility for the default robot. It is possible to call this function multiple times, with different x, y positions. However, if there is only one remaining initial position, such calls will be ignored to ensure that there is always a robot present.

If x, y is not an initial position no change is being made and a message is logged in the browser's console.

Parameters:
Name Type Description
x integer

The position on the grid
y integer

The position on the grid
Source:
Throws:

  • Will throw an error if the the world does not contain a robot

  • Will throw an error if the initial position is not valid [not implemented yet]

remove_object(name, x, y [, options])

This function removes an object at a location.

Parameters:
Name Type Argument Description
name string

Name of the object
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
options object <optional>

A Javascript object (or Python dict) containing additional arguments

Properties
Name Type Argument Description
goal boolean <optional>

If true, this will represent a goal i.e. the number of object that must be put at that location.
number integer <optional>

The number of objects to add at that location; it is 1 by default.
all boolean <optional>

If true, all such objects will be removed.
Source:
Throws:

  • Will throw an error if (x, y) is not a valid location.

  • Will throw an error if name is not a known thing.

  • Will throw an error if there is no object to remove at that location

remove_obstacle(x, y)

This function removes an obstacle at a location.

Parameters:
Name Type Description
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
Source:
Throws:

  • Will throw an error if (x, y) is not a valid location.

  • Will throw an error if name is not a known thing.

  • Will throw an error if there is no obstacle to remove at that location

remove_pushable(name, x, y)

This function removes a pushable at a location.

Parameters:
Name Type Argument Description
name string

The name of a the "thing" used as a pushable.
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
options.goal boolean <optional>

Indicate if this is to be set as a goal
Source:
Throws:

  • Will throw an error if (x, y) is not a valid location.

  • Will throw an error if there is no such named pushable at that location.

  • Will throw an error if name is not a known thing.

remove_wall(orientation, x, y [, goal])

This function removes a wall at the stated stated position and orientation if there there is one already located there; otherwise, it raises an exception.

Parameters:
Name Type Argument Description
orientation string

One of "east", "west", "north", "south".
x integer

Position: 1 <= x <= max_x
y integer

Position: 1 <= y <= max_y
goal bool <optional>

If true, get information about goal walls.
Source:
Throws:

  • Will throw an error if x or y is outside the world boundary.

  • Will throw an error if orientation is not a valid choice.

  • Will throw an error if there is no wall to remove.

set_background(url)

Uses a single image to fill the background. If the image is smaller than the world, it is stretched to fill the entire world. If it is larger than the world, it is cropped, with its bottom left corner coinciding with the bottom left corner of the world.

Parameters:
Name Type Description
url string

The url where the image is located.
Source:

set_extra_content(python_code [, hidden])

"Installs" a python module defined as a string parameter to this function. When called, the extra editor tab is shown in read-only mode. Once "installed", this content remains available only during the current browser's session. It can be updated at any time by calling this function again. It is suggested to call this function from the Onload editor, as part of the world creation.

Parameters:
Name Type Argument Description
python_code string

The Python code which is the content of the desired module, and shown in the extra editor tab.
hidden bool <optional>

If true/True, the extra editor tab (and its content) will be hidden.
Source:
Example
# set the content from a string
RUR.set_extra_content('''
def turn_right():
    turn_left()
    turn_left()
    turn_left()
''')

# set the content from the code present in the editor
# when saving/creating the world
RUR.set_extra_content(RUR.get_editor_from_world())

# similar to the above except for code in the library
RUR.set_extra_content(RUR.get_library_from_world())

set_model(model)

This function, intended for world creators, allow to set the model for the default robot, overriding the user's default choice.

Parameters:
Name Type Description
model string

The name of the model
Source:

set_random_orientation( [robot_body])

This function sets the initial (starting) orientation so that it will be chosen randomly.

Parameters:
Name Type Argument Description
robot_body object <optional>

Optional robot body object
Source:
Throws:

Will throw an error if it is called without an argument and the world does not contain a robot.

set_world_size(max_x, max_y)

Change the size of the world

Parameters:
Name Type Description
max_x integer

The width of the world. Internally, we use cols instead of max_x.
max_y integer

The height of the world. Internally, we use rows instead of max_y.
Source:

show_all_robots()

This method shows all known robot models in a table.

Source:

show_all_things( [property])

This method shows all known "things" in a table, with the exception of those defined with the color attribute. If a language other than English is selected, the translated name appears as well; this can be helpful to identify missing translations. If multiple images are shown, it means that the "thing" is shown as an animation in a world. Missing images in the goal column indicate that this "thing" cannot be used as an object to be picked up by Reeborg.

Parameters:
Name Type Argument Description
property string <optional>

If this argument is provided, only "things" for which this property/attribute is defined will be shown, and the value of the attribute will be shown as well.
Source:
Example
RUR.show_all_things()
RUR.show_all_things("fatal")

show_description()

Ensures that the world description window (usually open from World Info button for English UI) is shown.

Source:

show_detailed_diff(expected, actual [, options])

This function compares two strings and returns a summary of what was expected, followed by an output showing the differences as highlighted. This can be used, for example, to compare the output of a print statement written by a student to an expected output. If one wants to compare the result of a function returning a string, an additional option is to also show the actual output.

Note: if you or one of your students find the color differences between the inserted text and the deleted text too hard to distinguish, please get in touch with me so that I can make this work better.

Parameters:
Name Type Argument Description
expected string

The expected string
actual string

The string that was obtained (from the student code)
options Object <optional>

A Javascript object (Python dict) containing some additional optional options.

Properties
Name Type Argument Description
semantic boolean <optional>

If set to true, a semantic comparison (word by word) is attempted rather than a character by character comparison. This may give a more readable output in some cases.
expected_heading string <optional>

A string to use as the heading for the expected result.
differences string <optional>

A string to use as the heading for the highlighted differences.
show_actual boolean <optional>

If we wish to also display the actual result.
actual_heading string <optional>

A string to use as the heading for the actual result. This will be ignored if options.show_actual does not evaluate to true.
Source:
Returns:

A formatted html string.

Type
string

show_diff(expected, actual [, semantic])

This function compares two strings and returns a single html string with any differences highlighted. Newlines are converted to ⏎ followed by <br>. The typical use case is to compare an expected result to the one actually observed.

Note: if you or one of your students find the color differences between the inserted text and the deleted text too hard to distinguish, please get in touch with me so that I can make this work better.

Parameters:
Name Type Argument Description
expected string

The expected string
actual string

The string that was obtained (from the student code)
semantic boolean <optional>

If set to true, a semantic comparison (word by word) is attempted rather than a character by character comparison. This may give a more readable output in some cases.
Source:
Returns:

The content of the print output as a specially formatted html string.

Type
string

show_editors_content(show)

Used to show (or not) the content of the various world editors in the world's description (World Info button for English UI).

Parameters:
Name Type Description
show bool
Source:

show_path(path [, color])

This function draws a path which Reeborg should follow. To stop drawing the path, call the function with no arguments.

Parameters:
Name Type Argument Description
path list

A path, as printed by RUR.print_path.
color string <optional>

The color to be used to draw the path; the default is "lightsteelblue".
Source:

unmark_task(name)

Removes the tasks from the list of completed tasks. If the task cannot be found, the function will fail silently.

Parameters:
Name Type Description
name string

The name of task as it appears in the world selector, like Home 1.
Source:

world_init()

This function is called automatically just before a program is run. It identifies which objects (including goals) are initially assigned unknown random values, and assigns the required values. A world creator should never need to call this function.

Source:

world_map()

This function returns a World as a json object. Since the internal structure of worlds is subject to change, it is not advised to make use of this function inside a world definition.

However, when using Javascript, it can be useful as a means to explore the world structure, or assign advanced students to write their own functions based on the world structure (for example: find the shortest path in a maze using various search algorithms.)

When using Python, see SatelliteInfo() instead.

Source: