Scripting:Map View

Map View Scripting

Purpose

The part of the map that will be visible to the player is determined by the map view. The map view in turn is controlled by a Python script that is executed once per frame. Normally, the map view should stay focused on the player character, which is achieved through the method

   def focus_on_character (self, [world.mapview] view, [world.character] character):
       view.center_on (character.x(), character.y(), character.ox(), character.oy())
       if character.ground_pos() != view.get_z():
           view.scroll_to_z (character.ground_pos(), 2)

However, there are situations where this might not be the case. Cutscenes or a "magic eye" spell that may want to move the view independent of the player (or some other) character.

The following paragraphs explain how custom map view schedules will have to look like and how they can be used.

Basic Interface

Map view schedule scripts are kept in a package called schedules.map. The method

   [bool] set_schedule ([string] script, [string] method, [tuple] extraArgs*);

of the mapview class is used to assign a (new) schedule to an existing view. (TODO: how to get a reference to a map view in the first place?). It expects the name of the Python script (without the file extension), the name of the method to call in that script and an (optional) tuple of arguments that will be passed to that method. The script needs to contain a class of the same name as the file itself. The return value indicates whether setting the script was successful or not.

The signature of the method called to position the view is

   [void] def method (self, [world.mapview] view, opt_arg1, opt_arg2, ..., opt_argN):

where view is a reference to the map view the schedule is assigned to and opt_arg1 to opt_argN are the elements of the tuple passed to set_schedule. Those optional arguments should only consist of string or integer values, so they can be serialized when saving the game.

It should be noted that only one instance of each script will exist at runtime, so care needs to be taken if there are multiple map views active simultanously that access members of the same map view schedule class.