SPON Core v0.5.3
Copyright (C) 2007-2008 Bil Bas (bil dot bagpuss at gmail dot com / a.k.a. Spooner)
License: GNU Lesser General Public License, version 3
Overview
Core components required by most of the other SPON script packs (the README
for each package will say whether it actually requires SPON Core and what
minimum version is required). Many of the features provided here might be
of use in creating your own mission scripts.
SPON Core is avilable in two versions. One is an addon and the other is
mission-script-based which does not require any
addons to be installed on client or server. It requires ArmA 1.09 or higher.
Features
Standard
- Provides common features used by other SPON components, such as SPON VBIED,
SPON Recognise and SPON Map.
- User event handling: Any player (client) or server can broadcast local or global events. Those that have
previously registered for the event will have their code run (Used very
similarly to standard ArmA public variable events, but handler is run on local as well as remote machines).
- Broadcasting object variables with SPON_publicObjectVariable.
- Key event handling: Allows de-coupled key event handlers to be set up (normally a new key
event handler deletes any existing handler).
- Some global variables (read-only) to complement the built-in "isServer".
- SPON_formatTime function is available: Formats an elapsed time, in seconds, as 0:00:00 or 0:00:00.000, which is
appropriate for formatting elapsed time ("time" command), but not time of
day.
Optional
- Debug log:
- Makes a permanent record of all debug messages, viewable in a window, thus
not cluttering up the chat window with debug messages.
- Allows the client to view all debug messages that have been generated on
the client or the server at any time (JIP clients can only see server
messages generated after they joined)!
- Automatic monitoring of in-game men and vehicles:
- Lists of player, men and vehicle objects in the mission are kept updated.
- SPON events are published whenever any of these is found on the server for
the first time and when a player is first or last found on the server.
These events can be used to perform init actions on the objects, without
the need of addons (Although init might be slightly delayed after the
object has been created).
Installation (addon version)
- Install the XEH (Extended event handlers) addon by Solus.
- Copy the "Addon Version/@SPON_Core" directory into your ArmA directory.
- Add " -mod=@XEH;@SPON_Core" to your ArmA shortcut target.
- SPON Core will then be available in any mission with default settings
(see the next section to see what the default settings are).
Installation (mission-script version)
Required
- Copy the "SPON" directory from "Scripts" into your mission directory.
- Add the following lines to your mission's "stringtable.csv" file
(only #include the file from Core once, regardless of how many SPON
components are used):
LANGUAGE, "English"
#include "SPON\Core\stringtable.csv"
-
Add the following lines to your mission's "description.ext" file
(this must be before the files for any other SPON components are #included):
#include "SPON\Core\ui\core.hpp"
Optional
- If you wish to use the SPON debug log in your own scripts
then copy "SPON\Core\macros\macros.inc.sqf" into your script directory and put
these line at the top of any script you want to debug:
#define SPON_THIS_FILE MyFolder\MyFile
#include "macros.inc.sqf"
SPON_THIS_FILE should be defined as the file's path,
but it could be set to any descriptive text.
If defined, then this will be prepended to any debug message.
-
If you wish to use the SPON macros in your own scripts then copy
"SPON\Core\macros\macros.inc.sqf" into your script directory and put this
line at the top of any script you want to use macros in:
#include "macros.inc.sqf"
- If you want to use vehicle-monitoring in your own scripts, make sure that
the following line has been run before using any of the vehicle monitoring
functionality (if a SPON component needs to monitor vehicles, it will start
the monitor automatically, however no problems will be caused if this
function is called more than once):
[] call SPON_monitorVehicles;
Note that the delay between vehicle monitoring updates is set when SPON Core
is initiated, not when monitoring begins. This is because any number of
components might try to start the monitoring and it is best that the poll
delay is set in one place only.
- If you don't like the default GUI schema used, which is black text on a
light, opaque background, either alter "SPON\Core\ui\schema.hpp", or copy
one of the example schema from
"Example Schema\<schema-name>\schema.hpp" over this file. The
settings in the schema file will be used by SPON Core and any SPON
component scripts that have a GUI element.
Usage
- User event handling:
- SPON_addEventHandler to register a handler for an event (event handler
block called with [_eventName, _parameters]).
- SPON_removeEventHandler to remove handler for an event.
- SPON_publishGlobalEvent to initiate a global event which will be sent to
every handler registered for that event on every machine.
- SPON_publishLocalEvent to initiate a local event which will be sent to
every handler registered for that event.
- Key event handling:
- SPON_addKeyEventHandler (key event handler called with [_keycode, _shift,
_control, _alt]).
- SPON_removeKeyEventHandler
- Broadcasting variables attached to objects (those set with setVariable) in
a similar way as global variables are broadcast with publicVariable.
- SPON_publicObjectVariable (parameters are [_object, _variableName]).
- Some global variables (read-only) to complement the built-in "isServer":
- SPON_isClient - Machine is single-player or multi-player client.
- SPON_isDedicatedServer - Multi-player server machine.
- SPON_isDedicatedClient - Multi-player client machine.
- SPON_isMP - Machine is running in a multi-player game (server or client).
- Debug log:
- Using SPON_TRACE_* macros, found in debug.inc.sqf, which both
automatically adds the filename (if SPON_THIS_FILE is defined in the file)
and formats the list of traced variables nicely.
- Automatic monitoring of in-game men and vehicles:
- If you need to be sure that the info in the global variables is up to
date, then just "call SPON_recordVehicles;" first.
- Global (read-only!) arrays are maintained:
- SPON_men [Array of "Man", living AI and players]
- SPON_vehicles [Array of all crewable vehicles: land, sea and air]
- Associative lists describing players (Note that the order of these
lists is very unlikely to be identical on all machines):
- SPON_players_object [Array of player Objects]
- SPON_players_name[Array of String]
- SPON_players_connected [Array of Boolean]
- Events:
- "SPON_manFound" (local / Man has been seen for the very first time -
AI and players):
- Parameter 0: Soldier object found.
- "SPON_vehicleFound" (local / Crewable vehicle has been seen for the
first time):
- Parameter 0: Vehicle object found.
- "SPON_playerConnected" (local / Player has joined the game):
- Parameter 0: Player object (may previously have been an AI, in
which case it has already published a "SPON_manFound" event).
- "SPON_playerDisconnected" (local / Player has left the game):
- Parameter 0: Old player object (will be objNull unless the
disconnecting player has been taken over by AI).
- Parameter 1: Player name (before disconnection).
SPON_formatTime function:
[_time, _showMilliseconds] call SPON_formatTime;
Parameters:
- _time - Time to format, usually taken from "time" command
[Scalar: 0+]
- _showMilliseconds - Whether to show milliseconds after time
("0:00:00.000") or not ("0:00:00") [Boolean]
Returns: Formatted time [String]
SPON_addPermanentAction function:
[<parameters same as addAction command>] call SPON_addPermanentAction;
Parameters: As with addaction.
Returns: nil
Limitations
Compatibility
- Addons and Scripts:
- If SPON mission-script is used with SPON addon, only the addon version will be run (so ensure your addons are up to date).
- (Mission-version only) If SPON Core debug log is used with keys,
rather than action to open the map, it is not compatible with any
other script or addon that detects key-presses (unless it uses SPON Core
or Shole's DEH key-press handlers, of course).
Known Bugs
- Variables updated with SPON_publicObjectVariable are not automatically
updated for JIP players (though JIP players will get any new values
sent after they have joined).
- Debug message logging on dedicated servers is currently broken.
Plans
- Improvement of the debug log, so that messages can be filtered.
- Expand USAGE section in README.txt, to make the systems more usable by third
parties
Design Aims
- Provide a common set of scripts to minimise the repetition of scripts within
the other SPON components.
- To provide a strong base for anyone developing SP, and especially MP, missions.
- Consistent GUI across all SPON GUI-based components. Font/colour schema can be
chosen from a selection of standard schema.
- Avoid addons, in favour of scripting, as far as possible. Addon version and 100% mission-scripts versions are available!
Credits
- Significant testing and feedback provided by members of
the Regiment of Grenadier Guards [RGG] squad (http://www.rggsquad.co.uk).
Thanks fellas!
- Testing by various members of the IC-ArmA tournament.
- Thanks to everyone at BIS and OFPEC forums for testing, feedback and suggestions.
- Demo mission pbo file created with cpbo by Keygetys.
- Thanks to Solus for allowing me to include the XEH addon in the release (and, of course, for making the great addon in the first place!)
Change Log
v0.5.3
Fixed
- Using the debug log can reset the value of nil.
- Adding multiple key event handlers to one key will cause only the first to be run [Reported by i0n0s].
- SPON_isMP is incorrectly set to true in SP missions (unless you are playing from the SP editor without saving the mission).
v0.5.1
Modified
- Replaced Gnu Public Licence (GPL) with the less restrictive Lesser GPL (LGPL).
Fixed
- If SPON Core addon is loaded and SPON Core mission-scripts are run in the mission, then "things" get in a mess.
- SPON Core key event handlers incompatible with Shole's Display Event Handlers (If both are used, DEH's key events will always work, while SPON's won't).
- Some errors in macros.inc.sqf
v0.5.0
This is the first version available as an addon as well as a mission-script.
Added
- Assertion macros for design by contract (SPON_ASSERT(),
SPON_ASSERT_FALSE(), SPON_ASSERT_OP() and SPON_ASSERT_DEFINED())
- Error dialog with SPON_ERROR() macro provided to raise errors.
- SPON_addPermanentAction implemented.
- Added stringtable.csv to allow for internationalisation.
- Now available as an addon as well as a mission script.
- Lots of new utility scripts which might get documented one day.
Modified
- Simplification: You now just #include "SPON\Core\ui\core.hpp"
(before you included common.hpp and, optionally, debug.hpp)
- Merged debug.inc.sqf with macros.inc.sqf
- Debug log now opened via an action by default
Fixed
- SPON_isMP is false on the hosting player's machine in non-dedicated MP games.
- Debug mode parameter is case dependent.
v0.2.0
Added
- SPON_publicObjectVariable function
Modified
- Now requires Arma 1.09 or higher.
Fixed
- Cannot send object, group or side types in SPON events parameters
v0.1.2
Added
- Documented SPON_isClient, SPON_isDedicatedServer, SPON_isDedicatedClient
and SPON_isMP variables.
- SPON_GET_DEFAULT_PARAM() added to "macros.inc.sqf"
- Separated colour/font information into "SPON\Core\ui\schema.hpp". Provided
several example schema files so users can decide on which schema they'd
prefer to use (the default is dark/transparent).
Modified
- Content of this README reorganised and clarified.
- Reduced text-size for the debug-log.
Fixed
- Vehicles monitoring is always being started. It should only start if a
SPON component or user calls SPON_monitorVehicles.
- Client log messages can appear in dialogs other than the debug log,
found when using SPON Map, but could affect other dialogs.
- Size of text on SPON_rscMap control is much too large.
- Possible to open the debug log while it is already open, meaning it needs
to be closed multiple times if player keeps pressing the open log key.
v0.1.1
Added
- SPON_players_object, SPON_players_name & SPON_players_connected lists.
- "SPON_playerConnected" and "SPON_playerDisconnected" events.
Modified
- Split "SPON\Core\macros.inc.sqf" into "macros.inc.sqf" and "debug.inc.sqf"
v0.1.0
Modified
- Replaced SPON_publishEvent with SPON_publishLocalEvent and
SPON_publishGlobalEvent.
v0.0.21
- Original release as part of SPON Scripts