Overseer Object
This is the global application object. With it, the 3D cartographer can access most of the other Overseer-specific objects such as the GUI or World.

Properties (Methods)

(appPath, ChoiceBox, EntityFactory, errorReporting, lastCommand, lastKey, mapPath, mapTitle, OnDayZone, onKeyboard, onMouseClick, onMouseMove, OnTravelerStep, onUserMenu, onUserText, onWeatherChange, Traveler, viewMode, Window, World)
String appPath
a String containing the full path to City Overseer 3D®.
Object ChoiceBox
(See Object description for details.)
Object EntityFactory
(See Object description for details.)
boolean errorReporting
When set to true (default) message box will be displayed with last error details. To prevent endless message box loop you can set this value to false. Answering "No" on default message box request to display more errors also sets this value to false.
String lastCommand
The most recently entered user text command.
long lastKey
The last key pressed by the user. The possible values can be found at MSDN.
String mapPath
a String containing the full path to the currently loaded map. mapPath+mapTitle results in the complete pathname for the currently loaded map.
String mapTitle
a String containing the filename of the map. mapPath+mapTitle results in the complete pathname for the currently loaded map.
String onDayZone
This String is empty by default and optional. It can be set to an expression that evaluates when part of the day cycle changes. During a normal day cycle (i.e. without changes caused by user key presses), this expression will be evaluated 8 times – at midnight, twilight, dawn, morning, noon, afternoon, evening, and dusk.
String onKeyboard
This String is empty by default and optional. It can be set to an expression that evaluates when the user presses a key on the keyboard. The last key pressed can be read from lastKey or can be determined using the GetKeyState method. The expression is converted to a boolean value. If false, this key press is considered fully processed and ignored by the rest of the application.
String onMouseClick
This String is empty by default and optional. It can be set to an expression that evaluates when the user clicks the mouse. Additional information about the last click can be accessed using the Overseer.World.ClickRay object. The results of this expression will be converted to a boolean value. If false, the click is considered fully processed by the expression. Therefore, it will not be processed by other application procedures such as hotspot click activation.
String onMouseMove
This String is empty by default and optional. It can be set to an expression that evaluates when the user movess the mouse. The results of this expression will be converted to a boolean value. If false, the mouse move is considered fully processed by the expression.

String onTravelerStep
This String is empty by default and optional. It can be set to an expression that evaluates when the traveler makes a step. The results of this expression will be converted to a boolean type. If it is true, the step is allowed. Otherwise, the step is restricted and the traveler will stay in the current position. While the expression is being evaluated, Overseer.Traveler.GetPos() will return the new position, or where the traveler is about to step.
String onUserText
This String is empty by default and optional. It can be set to an expression that evaluates when the user enters a line of text and before it is compared with any keyword hotspot in the area. The results of the expression will be converted to a boolean type. If it is true, processing will pass to the hotspot as usual. Otherwise, processing ends and the hotspot is not notified about this input.
String onWeatherChange
This String is empty by default and optional. It can be set to an expression that evaluates when the weather changes.
Object Traveler
(See Object description for details)
long viewMode
Use this property to read or change the current view mode. Setting viewMode affects settings in the Overseer.World.Traveler object. The following values are supported:
O3D_CLIMB
 Travel on map surface with no gravity. Traveler will always be on top of objects.
O3D_FLY
 Travel over map surface in Dragon Flight mode.
O3D_OVERVIEW
 Leave map surface and return to Overview Mode.
O3D_TRAVEL
 Travel on map surface in Traveler Mode. The traveler's path can be blocked by tall objects and the traveler can walk under overhanging objects
Object Window
long left;
long top;
long right;
long bottom;
long width;
long height;
long mouseFlags;
long mouseX;
long mouseY;

void SetPos(long left, long top);
void SetSize(long width, long height);
void MoveWindow(long left, long top, long width, long height);
long GetHWND();
(See Object description for details)
Object World
(See Object description for details)
Methods (Properties)

(ActiveXObject, AskBox, BlipBox, ClearCallback, CreateFileDialog, CreateDataForm,  DeleteCampaignVars, ExitFS, Get2DEntCount, Get3DEntCount, Get2DEntity, Get3DEntity, GetCampaignVar, GetEntity, GetKeyState, GetLayerID, GetLayerName, GetObject, GetTextEntCount, GetTextEntity, GetTickCount, Include, Eval,  LoadMap, LoadMapChanges, MsgBox, OpenDoc, RunApp, ReportFPS, Roll, SaveMapChanges, SetCallback, SetCampaignVar, SetGridHeight  SetLayerState, SetSecurityLevel, SetStatusText, SetUserGUI, SwitchToFS, SysInclude, ThisEntity)
Object ActiveXObject(String name, String host)
This method creates and returns an ActiveX automation object from the String variable name. This variable String should contain the name of the automation server, a dot, followed by the type or class of the object. For example, InternetExplorer.application. The String host is optional and would contain the name of the network server where the object is to be created.
String AskBox(BSTR title, BSTR prompt)
The method creates a dialog box with title and prompt text. The user can then enter a line of text in the dialog. The return value is a String containing the line of text entered by the user.
void BlipBox(String msgText, double timeOut)
This method creates a simple box with no buttons that disappears on its own after timeOut seconds. Use it to display quick messages to the user without stopping script flow to wait for user input.
void ClearCallback(String expression)
Clears the callback of expression. If multiple instances of expression are being called, the first one set will be cleared first.
String CreateFileDialog(BOOL bOpenFile, LPCTSTR sDefExtension, LPCTSTR sDefFilename, long dwFlags, LPCTSTR sFilter)
This function is creates MFC standard file dialog and returns full file path (GetPathName) as result. If user cancels dialog, function returns empty string. You can combine the following flags (or use their exact values):

OFN_READONLY 0x00000001
OFN_OVERWRITEPROMPT 0x00000002
OFN_HIDEREADONLY 0x00000004
OFN_NOCHANGEDIR 0x00000008
OFN_SHOWHELP 0x00000010
OFN_ENABLEHOOK 0x00000020
OFN_ENABLETEMPLATE 0x00000040
OFN_ENABLETEMPLATEHANDLE 0x00000080
OFN_NOVALIDATE 0x00000100
OFN_ALLOWMULTISELECT 0x00000200
OFN_EXTENSIONDIFFERENT 0x00000400
OFN_PATHMUSTEXIST 0x00000800
OFN_FILEMUSTEXIST 0x00001000
OFN_CREATEPROMPT 0x00002000
OFN_SHAREAWARE 0x00004000
OFN_NOREADONLYRETURN 0x00008000
OFN_NOTESTFILECREATE 0x00010000
OFN_NONETWORKBUTTON 0x00020000
OFN_NOLONGNAMES 0x00040000 // force no long names for 4.x modules
OFN_EXPLORER 0x00080000 // new look commdlg
OFN_NODEREFERENCELINKS 0x00100000
OFN_LONGNAMES 0x00200000 // force long names for 3.x modules
OFN_ENABLEINCLUDENOTIFY 0x00400000 // send include message to callback
OFN_ENABLESIZING 0x00800000
DataForm CreateDataForm()
Creates new DataForm object. 
void DeleteCampaignVars(String campaign)
Deletes all values stored in the registry for the current user for campaign.
void ExitFS()
This function will switch City Overseer® to window mode from full screen mode. If already in window mode, this function does nothing. Use this function to explicitly return to window mode to gather user input.
long Get2DEntCount()
Returns the number of 2D entities (polygons, multi-polygons, symbols without 3D models, etc.) contained in the currently loaded map.
long Get3DEntCount()
Returns the number of 3D entities (3D models, 3D hotspots, etc.) contained in the currently loaded map.
Entity Get2DEntity(long entityPos)
Returns an entity from the 2D entity engine list. entityPos is a number from 0 to Get2DEntCount().
Entity Get3DEntity(long entityPos)
Returns an entity from the 3D entity engine list. entityPos is a number from 0 to Get3DEntCount().
String GetCampaignVar(String campaign, String varName)
Retrieves the value of varName from campaign section of the current user's registry entries.
Entity GetEntity(long tagNumber)
Primary method for access to map entities. Returns the entity that corresponds to tagNumber. If tagNumber was not found, this method returns null.
long short GetKeyState(long key)
Returns the state of the key indicated. The key can be any of the values found at MSDN.
long long GetLayerID(String layerName)
Returns the ID number for the named layer.
String GetLayerName(long layerID)
Returns the name of the layer with ID number layerID. All Entity objects store layers by ID number, not name.
long GetTextEntCount()
Returns the number of Text objects contained in the currently loaded map.
Entity GetTextEntity(long entityPos)
Returns an entity from the Text entity engine list. entityPos is a number from 0 to GetTextEntCount().
bool Include(String fileName)
Opens and parses another JScript file. Returns true if the file is found. If fileName String does not contain ":\" or ":/", it is assumed to be a relative path and mapPath is added to obtain the full path to the file to be opened.
VARIANT Eval(String jsExpression)
Evals JScript (OverseerScript) expression and returns the result if any. This is useful if you need to inject some data into Overseer3D object scope from external application - like Excel spreadsheet, Word document or web browser.
String LoadMap(String fileName, String locationName)
Resets Jscript engine, loads the map specified in fileName, and places the traveler at locationName. If the String fileName does not contain ":\" or ":/", it is assumed to be a relative path and mapPath is added to fileName to obtain the full path name to the map being loaded. The return value is the full path string of the map which is scheduled to load. Since loading the map reinitializes the script engine and all map entities, including the entity which causes the new map to load, the new map cannot be loaded immediately. This command only schedules for the new map to load. Always exit the script immediately following this instruction as there is no guarantee of how much time further instructions will have to execute before map load begins.
void LoadMapChanges(String changeFileName)
Loads the specified file, created using the SaveMapChanges() method, and uses it to update the current map.
long MsgBox(String text, String title, long flags)
Displays a standard Windows™ message box. The String title will be used as the title of the box, while text will be displayed inside the box. The long flags can be used to control the icons and buttons displayed with the message box. Legal values are listed below and may be combined using the OR operator.

Button flags
MB_ABORTRETRYIGNORE
MB_HELP
MB_OK
MB_OKCANCEL
MB_RETRYCANCEL
MB_YESNO
MB_YESNOCANCEL		 Abort, Retry, & Ignore buttons
Extra Help button
Box with only an OK button
OK and Cancel buttons
Retry and Cancel
Yes & No buttons
Yes, No, & Cancel buttons

Icon flags

MB_ICONHAND
MB_ICONQUESTION
MB_ICONEXCLAMATION
MB_ICONASTERISK

Hand Icon
Question Icon
Exclamation Icon
Asterisk Icon
Returns a long that is the ID of the button the user clicked. Check using the value or the following defined constants:
IDOK
IDCANCEL
IDABORT
IDRETRY
IDIGNORE
IDYES
IDNO
IDCLOSE
IDHELP

OK button, value = 1
Cancel button, value = 2
Abort button, value = 3
Retry button, value = 4
Ignore button, value = 5
Yes button, value = 6
No button, value = 7
Close button, value = 8
Help button, value = 9
long OpenDoc(String fileName)
Opens a document using the Windows™ registered viewer. If String fileName does not contain ":\" or ":/", it is assumed to be a relative path and fileName is added to mapPath to obtain the full path to the document. If the returned value is less than 32, an error has occurred.
long RunApp(String fileName)
Run the application specified in fileName. No path modifications are used in locating the program file.
void ReportFPS(bool bEnable)
Enables/disables frame-per-second report
double Roll(String diceRoll)
Calculates dice roll. Supports standard dice notations, parentheses and arithmetic operators. "2d20+2*d20+3*(-5+5d6-3d4*8d30)"
void SaveMapChanges(String changeFileName)
Used to save changes made to the current map. Changes are stored in the specified file for reload using the LoadMapChanges() method.
void SetCallback(String expression, long msDelay, long counter)
Use this method to set up an expression that will be executed every msDelay milliseconds. This will be done counter number of times. Set counter equal to –1 to execute expression indefinitely.

For example, SetCallback("FaeryDance(slowDance);",500, -1); would cause the function FaeryDance to be called with parameter slowDance every 500 milliseconds (.5 seconds) until the map is reloaded, City Overseer 3D® exits, or the callback is cleared using ClearCallback().
void SetCampaignVar(String campaign, String varName, String varValue)
Use this function to place variable values into the system registry for access by other maps. Values can thus be passed from map to map ensuring that a campaign progresses from beginning to end properly. The String campaign is a global string to identify variables belonging to the same campaign (set of maps). Variables are stored in the registry for the current user, thus multiple users could use the same series of maps and yet be at different points in the campaign. Access to the registry is slow, so dynamic storage of variables on the registry should not be attempted.
void SetGridHeight(double gridHeight)
All 2D entities on layer "HEX/SQUARE GRID" (CC2 default layer name) is considered to be a "Grid". SetGridHeight user can set the elevation of grid layer - which is very useful for combats which take place on the elevations (when 3D terrain covers the grid at 0-height).
long SetLayerState(String name, long state)
Sets the state for the named layer. Set state equal to a value of 1 for visible, 0 for hidden, or 2 for toggle. Returns the new layer status, or –1 if the layer was not found.
bool SetSecurityLevel(long level)
JScript has the ability to create and manage ActiveX objects. This application method can be used to change the security level for this script. If the new security level is equal to or lower than the current security level, this function returns true. If the new security level would result in lower security on the system, the user will be asked to approve of the change. If the user answers Yes, the application lowers the security level to the level requested and this method returns true. If the user answers No, the security level remains unchanged and the method returns false. Valid security levels and their description:
O3D_SECURITY_HIGH New ActiveXObjects are not allowed and GetObject() will return null.
O3D_SECURITY_MEDIUM ActiveX object Sripting.FileSystemObject is disabled.
O3D_SECURITY_LOW Everything is enabled.
void SetStatusText(String statusString)
String statusString is displayed on the application status bar.
void SetUserGUI(bool guiFlag)
Used to enable or disable the user GUI. Setting guiFlag to false will replace the user menu and keyboard shortcuts will a stripped–down version which will not allow changes in time, weather, viewing mode, etc. Any such changes should now come from within a script.
void SwitchToFS()
Explicitly switch to full screen mode.
bool SysInclude(String fileName)
Opens and parses another JScript file. Returns true if the file is found. If fileName String does not contain ":\" or ":/", it is assumed to be a relative path and appPath is added to obtain the full path to the file to be opened.
Entity ThisEntity()
In Activate(), DeActivate() functions, this method can be used to access properties and methods of the entity be activated/deactivated.


Copyright© 2001 Thought Guild Inc.