Module Wherigo
Wherigo Library, backward compatible with Wherigo Library by Groundspeak
Info:
| 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. |
| _Internal |
Virtual object to execute command with other item, same way as GetInput. |
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:
-
_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:
-
Distance (object) to nearest point of zone
-
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:
-
Distance (object) to nearest point of segment
-
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:
-
Distance object
-
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:
-
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:
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:
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:
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:
Returns:
True if object is a member of class
Class Wherigo.ZReciprocalCommand
ZReciprocalCommand object
-
Wherigo.ZReciprocalCommand.metatable
-
Metatable for ZReciprocalCommand objects. Implements tostring
Fields:
-
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:
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:
-
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:
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:
-
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:
-
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:
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:
-
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:
-
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:
-
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:
-
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:
-
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:
-
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:
-
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:
-
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