Module Wherigo

Wherigo Library, backward compatible with Wherigo Library by Groundspeak

Info:

Functions

MessageBox (t) Show message to user accepts table param or multiple parameters as below.
_MessageBoxResponse (action) Receives users response and calls desired callback.
Dialog (t) Shows series of messages to user, one after another.
PlayAudio (Media) Request to play user some audio.
ShowStatusText (Text) Shows status text somewhere.
VectorToZone (point, zone) Calculates distance from given point to nearest point of given zone
VectorToSegment (point, p1, p2) Calculates distance from given point to nearest point on segment of zone defined by two points (p1, p2)
Inject () Unknown purpose
IsPointInZone (point, zone) Determines whether is given point in given zone using Minimal Bounding Box algorithm and then with Cross Count algorithm
TranslatePoint (point, distance, bearing) Calculate new position of point, which is translated by given distance and with given bearing
VectorToPoint (p1, p2) Calculate distance and bearing from one point to another
NoCaseEquals (f, s) Compare two strings ignoring case
Command (text) Sends some command to engine
Possible values:
  • SaveClose - Saves cartridges and prompt user to quit
  • DriveTo - This should start Turn-by-turn navigation, but it is not used
  • StopSound - Stops playing sound in user interface
  • Alert - Beep.
LogMessage (Text, Level) Write message into logfile for opened cartridge params can be table
GetInput (input) Request user to fill in input.
_GetInputResponse (response) Callback of GetInput.
ShowScreen (screen, item) Sends request to user interface to show screen
__tonumber (arg) Conversion function from Distance or Bearing object to number used in metamethods to arithmetic and comparisons
_callback (event, id) Execute user command or click event on UI item.
_getMediaField (field, t) Get field with media path in JSON notation for UI.
_addCommands (item) Get Commands field with array of enabled commands for current object in JSON notation.
_bool2str (b) Convert boolean value to string for JSON notation.
_toJSON (str) Escape string to put in JSON structure.
_getUI () Get JSON fields to send to UI, containing all 4 sections, without brackets around, so C++ can add more fields.
_getLocations () Get Locations data in JSON to be send to UI.
_getInventory () Get Inventory data in JSON to be send to UI.
_getYouSee () Get YouSee data in JSON to be send to UI.
_getTasks () Get Tasks data in JSON to be send to UI.

Tables

_Internal Virtual object to execute command with other item, same way as GetInput.

Class Wherigo.Bearing

Wherigo.Bearing.metatable Metatable for Bearing objects.
Wherigo.Bearing.new (value) Bearing object constructor.

Class Wherigo.Distance

Wherigo.Distance.metatable Metatable for Distance objects.
Wherigo.Distance.new (value, units) Distance object constructor.
Wherigo.Distance:GetValue (units) Conversion function to get distance in other units

Class Wherigo.ZCommand

Wherigo.ZCommand.metatable Metatable for ZCommand objects.
Wherigo.ZCommand.new (table) ZCommand object constructor.
ZCommand:made (object) Check membership of given object to class ZCommand

Class Wherigo.ZReciprocalCommand

Wherigo.ZReciprocalCommand.metatable Metatable for ZReciprocalCommand objects.
Wherigo.ZReciprocalCommand.new (table) ZReciprocalCommand object constructor.
ZReciprocalCommand:made (object) Check membership of given object to class ZReciprocalCommand

Class Wherigo.ZObject

Wherigo.ZObject.metatable Metatable for ZObject objects.
Wherigo.ZObject.new (cartridge, container) ZObject constructor.
Wherigo.ZObject:Contains (obj) Check weather obj is contained in self container (recursive search) Special handling for Player and detecting if is in zone.
Wherigo.ZObject:MoveTo (owner) Move self object to another container or to nil
Wherigo.ZObject:_is_visible () Checks if self object is visible to player.
Wherigo.ZObject:_get_pos () Return position of object.
ZObject:made (object) Check membership of given object to class ZObject

Class Wherigo.ZonePoint

Wherigo.ZonePoint.metatable Metatable for ZonePoint objects.
Wherigo.ZonePoint.new (lat, lon, alt) ZonePoint constructor.
ZonePoint:made (object) Check membership of given object to class ZonePoint

Class Wherigo.Zone

Wherigo.Zone.metatable Metatable for ZonePoint objects.
Wherigo.Zone.new (cartridge) Zone constructor, extend ZObject.
Wherigo.Zone._calculateBoundingBox () Computes minimum bounding rectangle of this zone.
Zone:made (object) Check membership of given object to class Zone
Wherigo.Zone._update (v) Update zone state depending on location update.

Class Wherigo.ZCartridge

Wherigo.ZCartridge.metatable Metatable for ZCartridge object.
Wherigo.ZCartridge.new () ZCartridge constructor, extend ZObject.
ZCartridge:RequestSync () Request cartridge synchronization (store runtime data to file).
ZCartridge:GetAllOfType (t) Request all Z* objects by type
Wherigo.ZCartridge._update (position, t, accuracy) Process position update.
ZCartridge:made (object) Check membership of given object to class ZCartridge

Class Wherigo.ZMedia

Wherigo.ZMedia.metatable Metatable for ZMedia objects.
Wherigo.ZMedia.new (cartridge) ZMedia constructor, extend ZObject.
ZMedia:made (object) Check membership of given object to class ZMedia

Class Wherigo.ZItem

Wherigo.ZItem.metatable Metatable for ZItem objects.
Wherigo.ZItem.new (cartridge, container) ZItem constructor, extend ZObject.
ZItem:made (object) Check membership of given object to class ZItem

Class Wherigo.ZTask

Wherigo.ZTask.metatable Metatable for ZTask objects.
Wherigo.ZTask.new (cartridge, container) ZTask constructor, extend ZObject.
ZTask:made (object) Check membership of given object to class ZTask

Class Wherigo.ZTimer

Wherigo.ZTimer.metatable Metatable for ZTask objects.
Wherigo.ZTimer.new (cartridge) ZTimer constructor, extend ZObject.
ZTimer:Start () Starts timer (countdown) and execute attached event
ZTimer:Stop () Stops this timer and execute attached event
ZTimer:Tick () Timer expired.
ZTimer:made (object) Check membership of given object to class ZTimer
Wherigo.ZTimer._Tick (id) Internaly used function to call from C API.

Class Wherigo.ZInput

Wherigo.ZInput.metatable Metatable for ZInput objects.
Wherigo.ZInput.new (cartridge) Zinput constructor, extend ZObject.
ZInput:made (object) Check membership of given object to class ZInput

Class Wherigo.ZCharacter

Wherigo.ZCharacter.metatable Metatable for ZCharacter objects.
Wherigo.ZCharacter.new (cartridge, container) ZCharacter constructor, extend ZObject.
ZCharacter:made (object) Check membership of given object to class ZCharacter

Class Wherigo.Player

Player:RefreshLocation () Request new position update for special application.
Wherigo.Player._removeFromZone (zone) Remove zone from InsideOfZones table of Player.


Functions

MessageBox (t)
Show message to user accepts table param or multiple parameters as below. Params table:
  • Text string message to show (required)
  • Media ZMedia image to show with it
  • Buttons Table with text to show on buttons
  • Callback Function to call after user pushes on of the buttons

Parameters:

  • t
_MessageBoxResponse (action)
Receives users response and calls desired callback. Called only if callback was set. Internal usage only!

Parameters:

  • action Button1 or Button2 or nil depending on user choice
Dialog (t)
Shows series of messages to user, one after another. Internal using MessageBox. For more details @see MessageBox

Parameters:

  • t Table of tables with keys "Text" and "Media" to be shown
PlayAudio (Media)
Request to play user some audio. Sends request to user interface what handles it. If it is long, can be stopped by calling Command("StopSound")

Parameters:

  • Media ZMedia object containing audio to play
ShowStatusText (Text)
Shows status text somewhere. Not used and not well documented

Parameters:

  • Text What should be shown to user
VectorToZone (point, zone)
Calculates distance from given point to nearest point of given zone

Parameters:

  • point ZonePoint object as a starting location
  • zone Zone object as a destination

Returns:

  1. Distance (object) to nearest point of zone
  2. Bearing (object) to nearest point of zone
VectorToSegment (point, p1, p2)
Calculates distance from given point to nearest point on segment of zone defined by two points (p1, p2)

Parameters:

  • point ZonePoint object as a starting location
  • p1 ZonePoint, first point of segment
  • p2 ZonePoint, second point of segment

Returns:

  1. Distance (object) to nearest point of segment
  2. Bearing (object) to nearest point of segment
Inject ()
Unknown purpose
IsPointInZone (point, zone)
Determines whether is given point in given zone using Minimal Bounding Box algorithm and then with Cross Count algorithm

Parameters:

  • point ZonePoint object
  • zone Zone object

Returns:

    True if is point in zone
TranslatePoint (point, distance, bearing)
Calculate new position of point, which is translated by given distance and with given bearing

Parameters:

  • point ZonePoint object as a starting point
  • distance Distance object
  • bearing Bearing object or number to determine direction

Returns:

    ZonePoint object with new location
VectorToPoint (p1, p2)
Calculate distance and bearing from one point to another

Parameters:

  • p1 Starting ZonePoint
  • p2 Destination ZonePoint

Returns:

  1. Distance object
  2. Bearing object
NoCaseEquals (f, s)
Compare two strings ignoring case

Parameters:

  • f First string
  • s Second string

Returns:

    True if they equals
Command (text)
Sends some command to engine
Possible values:
  • SaveClose - Saves cartridges and prompt user to quit
  • DriveTo - This should start Turn-by-turn navigation, but it is not used
  • StopSound - Stops playing sound in user interface
  • Alert - Beep. Used on Garmins, which can't play sound

Parameters:

  • text Command
LogMessage (Text, Level)
Write message into logfile for opened cartridge params can be table

Parameters:

  • Text Message to log
  • Level Level of message
GetInput (input)
Request user to fill in input. Appearance depends on ZInput object

Parameters:

  • input ZInput object containing data about input appearance
_GetInputResponse (response)
Callback of GetInput. Internal usage only! This is called for every GetInput

Parameters:

  • response User's response (selected button or written string)
ShowScreen (screen, item)
Sends request to user interface to show screen

Parameters:

  • screen Screen name (see constants)
  • item For 'DETAILSCREEN' particular ZObject
__tonumber (arg)
Conversion function from Distance or Bearing object to number used in metamethods to arithmetic and comparisons

Parameters:

  • arg Number or object to convert

Returns:

    Number representing Distance in meters or bearing in degrees
_callback (event, id)
Execute user command or click event on UI item. OnClick is simply executed, other events On* of commands must be handled with care of command type. Internal use only.

Parameters:

  • event Event name in Commands table, or Click for OnClick event
  • id Global id in AllZObjects table
_getMediaField (field, t)
Get field with media path in JSON notation for UI. Internal usa only.

Parameters:

  • field String "media" or "icon" used as index in JSON
  • t Table value to chech and add it exists

Returns:

    String containing JSON notation of field or empty string if t is nil
_addCommands (item)
Get Commands field with array of enabled commands for current object in JSON notation. Internal use only!

Parameters:

  • item ZObject to get commands for

Returns:

    String containing JSON notation of commands field
_bool2str (b)
Convert boolean value to string for JSON notation. Internal use only!

Parameters:

  • b Boolean value

Returns:

    String value containing true or false
_toJSON (str)
Escape string to put in JSON structure. Just proxy to ignore nil values. Internal use only!

Parameters:

  • str String to escape

Returns:

    Escaped string
_getUI ()
Get JSON fields to send to UI, containing all 4 sections, without brackets around, so C++ can add more fields. Internal use only!

Returns:

    String containing JSON notation of UI data
_getLocations ()
Get Locations data in JSON to be send to UI. Internal use only!

Returns:

    String containing JSON
_getInventory ()
Get Inventory data in JSON to be send to UI. Internal use only!

Returns:

    String containing JSON
_getYouSee ()
Get YouSee data in JSON to be send to UI. Internal use only!

Returns:

    String containing JSON
_getTasks ()
Get Tasks data in JSON to be send to UI. Internal use only!

Returns:

    String containing JSON

Tables

_Internal
Virtual object to execute command with other item, same way as GetInput. Internaly substitutes ZInput object.

Fields:

  • Name

Class Wherigo.Bearing

Object representing a bearing in degrees.
Wherigo.Bearing.metatable
Metatable for Bearing objects. Implements arithmetic, call and tostring as required by cartridges

Fields:

  • __tostring
  • __call
  • __add
  • __sub
  • __mul
  • __div
Wherigo.Bearing.new (value)
Bearing object constructor. Number is automatically normalized to interval 0 - 360 degrees

Parameters:

  • value Numeric value representing bearing in degrees

Returns:

    Bearing instance

Class Wherigo.Distance

Object representing distance in meters.
Wherigo.Distance.metatable
Metatable for Distance objects. Implements arithmetic, comparison, call and tostring as required by cartridges

Fields:

  • __tostring
  • __call
  • __eq
  • __lt
  • __le
  • __add
  • __sub
  • __mul
  • __div
Wherigo.Distance.new (value, units)
Distance object constructor. Represent distance in meters

Parameters:

  • value Numeric value of distance (required)
  • units String representation of units in which is value set for conversion, default "meters"

Returns:

    Distance instance
Wherigo.Distance:GetValue (units)
Conversion function to get distance in other units

Parameters:

  • units String representation of units in which you want the result, default "meters"

Returns:

    Numeric representation of distance in required units

Class Wherigo.ZCommand

Object representing ZCommand of ZObject.
Wherigo.ZCommand.metatable
Metatable for ZCommand objects. Implements index, newindex to watch Enabled property and tostring

Fields:

  • __tostring
  • __index
  • __newindex
Wherigo.ZCommand.new (table)
ZCommand object constructor. Sets allowed combination of parameters

Parameters:

  • table Parameters of command to set

Returns:

    ZCommand object
ZCommand:made (object)
Check membership of given object to class ZCommand

Parameters:

  • object Some object

Returns:

    True if object is a member of class

Class Wherigo.ZReciprocalCommand

ZReciprocalCommand object
Wherigo.ZReciprocalCommand.metatable
Metatable for ZReciprocalCommand objects. Implements tostring

Fields:

  • __tostring
Wherigo.ZReciprocalCommand.new (table)
ZReciprocalCommand object constructor. Sets parameters from arguments. Not used in runtime.

Parameters:

  • table Parameters of command to set

Returns:

    ZReciprocalCommand object
ZReciprocalCommand:made (object)
Check membership of given object to class ZReciprocalCommand

Parameters:

  • object Some object

Returns:

    True if object is a member of class

Class Wherigo.ZObject

Base object for all next Z* objects. Implements all common
Wherigo.ZObject.metatable
Metatable for ZObject objects. Implements index and newindex to keep a track of desired properties and to invoke desired actions

Fields:

  • __index
Wherigo.ZObject.new (cartridge, container)
ZObject constructor. Sets default values and parameters of all objects. Also can accept table argument with all values to set

Parameters:

  • cartridge ZCartridge object of global cartridge
  • container Default location of object. Can be moved later by calling Wherigo.ZObject.MoveTo function

Returns:

    ZObject
Wherigo.ZObject:Contains (obj)
Check weather obj is contained in self container (recursive search) Special handling for Player and detecting if is in zone.

Parameters:

  • obj Object to check

Returns:

    True if self contains obj
Wherigo.ZObject:MoveTo (owner)
Move self object to another container or to nil

Parameters:

  • owner Destination container
Wherigo.ZObject:_is_visible ()
Checks if self object is visible to player. Internal use only!

Returns:

    True if is object visible
Wherigo.ZObject:_get_pos ()
Return position of object. Recurs into Container property. Internal use only!

Returns:

    ZonePoint object or nil if is position of object undefined
ZObject:made (object)
Check membership of given object to class ZObject

Parameters:

  • object Some object to test

Returns:

    True if object is a member of class

Class Wherigo.ZonePoint

ZonePoint object representing geographical point on sphere
Wherigo.ZonePoint.metatable
Metatable for ZonePoint objects. Implements tostring as required by cartridges

Fields:

  • __tostring
Wherigo.ZonePoint.new (lat, lon, alt)
ZonePoint constructor. Creates new ZonePoint object defined by geographical coordinates and altitude.

Parameters:

  • lat Latitude
  • lon Longitude
  • alt Altitude

Returns:

    ZonePoint object
ZonePoint:made (object)
Check membership of given object to class ZonePoint

Parameters:

  • object Some object to test

Returns:

    True if object is a member of class

Class Wherigo.Zone

Zone object extends ZObject. Location, defined with 3 or more ZonePoint.
Wherigo.Zone.metatable
Metatable for ZonePoint objects. Implements tostring as required by cartridges. Other metamethods are inherited from ZObject

Fields:

  • __tostring
Wherigo.Zone.new (cartridge)
Zone constructor, extend ZObject. Creates new Zone object.

Parameters:

  • cartridge global cartridge object

Returns:

    Zone object
Wherigo.Zone._calculateBoundingBox ()
Computes minimum bounding rectangle of this zone. Internal use only!
Zone:made (object)
Check membership of given object to class Zone

Parameters:

  • object Some object to test

Returns:

    True if object is a member of class
Wherigo.Zone._update (v)
Update zone state depending on location update. Recalculate distance and change state if required

Parameters:

  • v Zone object

Returns:

    True if changed. Unused.

Class Wherigo.ZCartridge

ZCartridge object extend ZObject. Global cartridge object to store all game data.
Wherigo.ZCartridge.metatable
Metatable for ZCartridge object. Implements tostring as required by cartridges. Other metamethods are inherited from ZObject

Fields:

  • __tostring
Wherigo.ZCartridge.new ()
ZCartridge constructor, extend ZObject. Creates new ZCartridge object and initializes all default values and structures for storing all game data

Returns:

    ZCartridge object
ZCartridge:RequestSync ()
Request cartridge synchronization (store runtime data to file). Only accepts the request and waits for the end of lua call stack and then stores data.
ZCartridge:GetAllOfType (t)
Request all Z* objects by type

Parameters:

  • t Requested type
Wherigo.ZCartridge._update (position, t, accuracy)
Process position update. Internal use only!

Parameters:

  • position ZonePoint object with player location
  • t Time to update timers
  • accuracy GPS position accuracy

Returns:

    If something changed, request GUI update
ZCartridge:made (object)
Check membership of given object to class ZCartridge

Parameters:

  • object Some object to test

Returns:

    True if object is a member of class

Class Wherigo.ZMedia

ZMedia object extend ZObject. Media object with defined resources.
Wherigo.ZMedia.metatable
Metatable for ZMedia objects. Implements tostring as required by cartridges. Other metamethods are inherited from ZObject

Fields:

  • __tostring
Wherigo.ZMedia.new (cartridge)
ZMedia constructor, extend ZObject. Creates new ZMedia object and initializes default values. Parameters can be in table.

Parameters:

  • cartridge ZCartridge object of global cartridge

Returns:

    ZMedia object
ZMedia:made (object)
Check membership of given object to class ZMedia

Parameters:

  • object Some object to test

Returns:

    True if object is a member of class

Class Wherigo.ZItem

ZItem object extend ZObject. Item that can be seen or that can be in inventory. This can have also some ZCommands.
Wherigo.ZItem.metatable
Metatable for ZItem objects. Implements tostring as required by cartridges. Other metamethods are inherited from ZObject

Fields:

  • __tostring
Wherigo.ZItem.new (cartridge, container)
ZItem constructor, extend ZObject. Creates new ZItem object and initializes default values. Parameters can be in table.

Parameters:

  • cartridge ZCartridge object of global cartridge
  • container Default container tu put

Returns:

    ZItem object
ZItem:made (object)
Check membership of given object to class ZItem

Parameters:

  • object Some object to test

Returns:

    True if object is a member of class

Class Wherigo.ZTask

ZTask object extends ZObject. Tasks given to player. Showing or hiding, but keeps user in track what to do.
Wherigo.ZTask.metatable
Metatable for ZTask objects. Implements tostring as required by cartridges. Other metamethods are inherited from ZObject

Fields:

  • __tostring
Wherigo.ZTask.new (cartridge, container)
ZTask constructor, extend ZObject. Creates new ZTask object and initializes default values. Parameters can be in table. Also keeps track of all tasks to set default SortOrder.

Parameters:

  • cartridge ZCartridge object of global cartridge
  • container Default location of object. Can be moved later by calling Wherigo.ZObject.MoveTo function

Returns:

    ZTask object
ZTask:made (object)
Check membership of given object to class ZTask

Parameters:

  • object Some object to test

Returns:

    True if object is a member of class

Class Wherigo.ZTimer

ZTimer object extends ZObject. Can invoke action in some time.
Wherigo.ZTimer.metatable
Metatable for ZTask objects. Implements tostring as required by cartridges. Other metamethods are inherited from ZObject

Fields:

  • __tostring
Wherigo.ZTimer.new (cartridge)
ZTimer constructor, extend ZObject. Creates new ZTimer object and initializes default values. Parameters can be in table.

Parameters:

  • cartridge ZCartridge object of global cartridge

Returns:

    ZTimer object
ZTimer:Start ()
Starts timer (countdown) and execute attached event
ZTimer:Stop ()
Stops this timer and execute attached event
ZTimer:Tick ()
Timer expired. Desired action is executed and timer reset. if type is interval, then it starts again
ZTimer:made (object)
Check membership of given object to class ZTimer

Parameters:

  • object Some object to test

Returns:

    True if object is a member of class
Wherigo.ZTimer._Tick (id)
Internaly used function to call from C API. Calls desired Tick event by given id in AllZObjects table

Parameters:

  • id ID from AllZobjects table

Class Wherigo.ZInput

ZInput object extends ZObject. Request input from user. Can be text or multiple choice
Wherigo.ZInput.metatable
Metatable for ZInput objects. Implements tostring as required by cartridges. Other metamethods are inherited from ZObject

Fields:

  • __tostring
Wherigo.ZInput.new (cartridge)
Zinput constructor, extend ZObject. Creates new Zinput object and initializes default values. Parameters can be in table.

Parameters:

  • cartridge ZCartridge object of global cartridge

Returns:

    ZTimer object
ZInput:made (object)
Check membership of given object to class ZInput

Parameters:

  • object Some object to test

Returns:

    True if object is a member of class

Class Wherigo.ZCharacter

ZCharacter object extends ZObject. Player or other character to be seen in inventory or in nearby zones.
Wherigo.ZCharacter.metatable
Metatable for ZCharacter objects. Implements tostring as required by cartridges. Other metamethods are inherited from ZObject

Fields:

  • __tostring
Wherigo.ZCharacter.new (cartridge, container)
ZCharacter constructor, extend ZObject. Creates new ZCharacter object and initializes default values. Parameters can be in table.

Parameters:

  • cartridge ZCartridge object of global cartridge
  • container Default container for character

Returns:

    ZCharacter object
ZCharacter:made (object)
Check membership of given object to class ZCharacter

Parameters:

  • object Some object to test

Returns:

    True if object is a member of class

Class Wherigo.Player

Global object representing player as ZCharacter with position.
Player:RefreshLocation ()
Request new position update for special application. Required by some cartridges. There is not implemented since I can't see point in it.
Wherigo.Player._removeFromZone (zone)
Remove zone from InsideOfZones table of Player. Required for runtime for some cartridges and used for savegame. Internal use only!

Parameters:

  • zone Zone object to remove
generated by LDoc 1.3.11