Introduction

Installation

Configuring Objects

Spacecalls

Events

Coordinates

Tips & Tricks

Portable Space EngineBuilder's Guide

Please send comments to Mark Cooke <mpc@star.sr.bham.ac.uk> or vspace@geocities.com

>Spacecalls: Alphabetical

SpacecallReturn ValueObjectShip
active(dbref object)Boolean   
This function returns a boolean flag indicating the presence of the given object in space.
add_object(dbref object)   
This command attempts to add the specified object to space. The PSE will attempt to read the attributes from the object, and create the internal structures needed. Any errors are logged to the space_debug_char and to the server log file.
add_timer(Integer first, Integer interval, Integer repeat, String id) X 
This command creates a new timer for the object. The first EV_TIMER event will occur after 'first' seconds, the remainder at 'interval' seconds thereafter. The 'repeat' count can be zero, which specifies that the event will repeat until it is deleted. 'id' is supplied back to the event as the first parameter. The second parameter is the number of times the timer has expired.
cause_damage(dbref target, Integer amount, Integer type) XX
This command causes a number of points of damage of the specified type to the target object. Types 0 to 2 are defined as 'gun', 'torp' and 'explosion' damage respectively. Intended use of this function is to provide softcoded weapons.
cause_system_damage(Integer system, Integer amount) XX
This command causes a number of points of direct damage to the specified system. Generally systems can take 3 points of damage before being completely destroyed. The system specifier here is very version specific, and users of this function should check the hard code for more details.
comm_freq(Int channel)Integer  X
This function returns the communications frequency of the selected channel. Each ship has 6 channels, labled 0 through 5.
comm_label(Int channel)String  X
This function returns the label of the selected channel. Each ship has 6 channels, labled 0 through 5. The label canbe changed using the comm_label_channel spacecall.
comm_label_channel(Int channel, String label)  X
This command changes the label of the selected channel. A channel label can be upto 16 characters long.
comm_send(Int channel, String message)  X
This command sends a message on the chosen channel. The channel must have its frequency set using comm_set_channel before this function will broadcast a message.
comm_set_channel(Int channel, Integer frequency)  X
This command changes the frequency of the selected channel. No messages can be sent on a channel, until a frequency is selected.
console_emit(Integer OrFlags, Integer AndFlags, String message)  X
This command sends the specified message to the consoles selected by the flags. A console is emitted to if it has all of the flags specified in the AndFlags mask, and at least one of the flags specified in the OrFlags mask. Details of the masks used are to be found in the source. This function will go away with the introduction of the new messaging module.
contact_info_level(Integer contact)Integer X 
This function returns the current information level of the specified contact. 0 indicates that the contact number is not valid. Values range from 1 (least visible) to 5 (most visible).
contact_info_string(Integer contact)String X 
This function returns information about the specified contact, or a string starting with #-1 if the contact given is invalid. The string contains the size, visibility (info_level), bearing, range, heading, speed, facing shield information and the name of the contact. It is provided so that writing custom contact list display functions is easy.
contact_list(Boolean show_ships, Boolean show_other) X 
This command causes the contacts meeting the criteria to be emitted to the enactor.
contact_list_dbrefs()String list X 
This function can be called for any active space object, and returns a space separated list of objects currently on sensors for the given object.
contact_list_num()String list X 
This function returns a list of space separated integers, which are the current contacts for the space object.
del_timer(String id) X 
This command deletes any timers on the object that have a matching id string. If the 'id' provided is empty, all the timers for the object are deleted.
dmg_repair(Integer team, String system)  X
This command assigns the specified damage control team to the given system. The assignment, or error string is returned to the consoles or enactor as appropriate.
dmg_system_status()  X
This command sends the current damage control status to consoles having the damage control flag set. It shows a list of damaged systems, and their current state of repair.
dmg_team_status()  X
This command sends the current damage control team status to consoles having the damage control flag set. It shows a list of damage control teams, and their current task.
drain_reactor(Integer points) XX
This command changes the number of points being drained from a ship reactor per turn. It can be used to simulate anomalies in space. Calling this command also triggers an EV_REACTOR_DRAIN event.
enable_console(dbref console, Boolean active)  X
This command enables and disables the specified console by setting or clearing the ACTIVE flag on the console. Consoles without the active flag set are not sent any PSE generated messages. However, softcoded commands can still be issued from the console, and the space designer will need to bear this in mind.
eng_alloc_batts()Integer  X
This function returns the current energy allocation to the batteries.
eng_alloc_nav()Integer  X
This function returns the total energy allocation to navigation.
eng_alloc_shields()Integer  X
This function returns the total energy allocation to shields.
eng_alloc_tac()Integer  X
This function returns the total energy allocation to tactical. This total is subdivided to phasers, torpedoes and tractor beam.
eng_allocate(Integer tactical, Integer navigation, Integer shields, Integer batteries)  X
This command allocates energy between tactical, navigation, shields and batteries. If the total allocated energy is greater than the available energy, the values are scaled down automatically.
eng_batt_disch()Integer  X
This function returns the current discharge rate for the batteries. If no batteries are present on the ship object, a zero is returned.
eng_batt_level()Integer  X
This function returns the current capacity for the batteries. If no batteries are present on the ship object, a zero is returned.
eng_batt_max()Integer  X
This function returns the maximum capacity for the batteries. If no batteries are present on the ship object, a zero is returned.
eng_batt_max_disch()Integer  X
This function returns the maximum discharge rate for the batteries. If no batteries are present on the ship object, a zero is returned.
eng_batt_status()String status  X
This function returns the current status of the batteries. The possible return values are OFF, ON and DAMAGED.
eng_battery_off()  X
This command switches the batteries off.
eng_battery_on()  X
This command switches the batteries on. Additional power, upto the battery maximum discharge rate is available per turn when batteries are on.
eng_output()Integer output  X
This function returns the current amount of energy being produced by the reactor.
eng_reactor_setting()Integer setting  X
This function returns the current reactor setting, as a percentage setting.
eng_set_reactor(Integer setting)  X
This command changes the current reactor setting. The setting is given as a percentage. The minimum percentage is 5%, and the maximum is configurable using the CF_REACTOR_LEVEL_STRESS ship attribute.
eng_shutdown_reactor()  X
This command shuts down a reactor. It is not allowed for objects in real space. For objects in simulated space, it removes the object from space.
eng_start_reactor(dbref ship)   
This command starts a ship reactor. It is not allowed for objects in real space, where objects should be launching or undocking. For objects in simulated space, it sets the reactor output to 5%, and adds the object to space.
eng_stress()Integer stress  X
This function returns the current level of stress for the reactor. Once 100% stress is reached, the engine will begin to suffer damage. Automatic warnings and safeties can be enabled and disabled using the eng_toggle_safe and eng_toggle_warn spacecalls.
eng_toggle_safe()  X
This command toggles the current setting of the reactor safety features. If enabled, the reactor will automatically reduce output when stress reaches 100% to prevent damage. It is enabled automatically when a ship object is added to space.
eng_toggle_warn()  X
This command toggles the current setting of the reactor warning features. If enabled, warning messages will be sent to engineering consoles as the reactor approaches 100% stress. This feature is automatically enabled when the ship object is added to space.
explosion(Integer space, Integer x, Integer y, Integer z, Integer damage)   
This command causes an explosion event to occur at the given coordinates in the specified space. It can be used to simulate minefields and so on, without putting hundreds of objects into space in close proximity to each other.
facing_shield(Dbref target)Integer shield X 
This function calculates the shield of the target which is facing the calling space object. The number returned is dependant on the shield array of the target object. It returns 0 if the object has no shields, and a string which starts with #-1 in the case of an error.
format_range_string(Integer range, Integer max_width)String X 
This function will perform some scaling of the provided value, and append an appropriate scale flag.
get_consoleflags(Dbref console)String  X
This function returns a space separated list of the flags which are set on the provided console, or a string starting with #-1 if the console is not valid for the space object.
get_debug_char()dbref   
This command returns the object database number to which PSE log messages are currently being echoed.
godspecs() X 
This command causes the space object specifications, including object and ship flags as appropriate to be emitted to the enactor.
has_console_flag(Dbref console, String flag)Boolean  X
This function returns true if the specified console has the given flag is set, or false if the flag is not set, or a string starting with #-1 if there was an error.
has_obj_flag(String flag)Boolean X 
This function returns true if the given flag is set, or false if the flag is not set (or is not a valid flag), or a string starting with #-1 if there was an error.
has_ship_flag(String flag)Boolean  X
This function returns true if the given flag is set, or false if the flag is not set (or is not a valid flag), or a string starting with #-1 if there was an error.
list_containers()String list X 
This function returns a space separated list of space objects which have the object on sensors and within critical range.
lookup_contact(Integer contact)Dbref X 
This function returns the dbref of the object associated with the specified contact number, or #-1 if the contact is not valid.
max_warp(Integer cost)Float warp  X
This function returns the maximum warp speed that can be achieved by the ship for the given amount of energy. Account is taken of the POKEY and SPEEDY flags, and the returned value is never more than the maximum speed permitted for the ship.
name()String X 
This function returns the name of the space object.
nav_close_doors()  X
This command closes the bay doors on the ship object.
nav_dock(Integer contact)  X
This command attempts to dock the space object with the specified contact. The contact must have openned the bay doors, and lowered shields.
nav_door_status()String status  X
This function returns the current state of the bay doors on the ship object. The possible return values are NONE, OPEN and CLOSED.
nav_heading()String heading  X
This function returns the current heading of the ship object in the standard order of bearing then elevation. The elevation is always preceeded by a + or - sign.
nav_land(Integer contact)  X
This command attempts to land the ship on the specified contact. The ship must have the CAN_LAND flag set, and the contact the must have the PLANET flag set.
nav_launch(dbref ship)   
This command attempts to launch the ship. The ST_DOCKED_AT attribute on the ship should be set to a valid planet already in space for this command to succeed.
nav_odometer()Integer distance  X
This function returns the distance travelled by the ship. The odometer function is a compile-time option, and hence may not be available.
nav_odometer_set(Integer distance)  X
This command changes the current value of the odometer on the ship to the specified value. The odometer function is a compile-time option, and hence may not be available.
nav_open_doors()  X
This command opens the bay doors on the ship object (if present).
nav_orbit(Integer contact)  X
This command puts the ship into orbit around the specified contact. The ship must be within docking range, and the contact must be a planet. The ship's ST_DOCKED_AT attribute is set, and EV_ORBIT_* events triggered.
nav_roll()Integer roll  X
This function returns the current roll angle for the ship. Roll is defined as a rotation around the direction of travel. A roll of 0 indicates the ship is parallel to the X-Y plane.
nav_set_course(Float bearing, String +/-, Float elevation)  X
This command specifies a new heading and elevation for the ship. Bearing should be between 0 and 360, and elevation between 0 and 90.
nav_set_roll(Integer roll)  X
This command specifies a new roll angle for the ship. Roll is defined as a rotation around the direction of travel.
nav_set_warp(Float speed)  X
This command specifies a new speed for the ship.
nav_speed()Float speed  X
This function returns the current speed of the ship.
nav_time_active()Integer seconds  X
This function returns the current amount of time that the ship has been in space. This value is cumulative, and so is not reset to zero then a ship launches or undocks. Time tracking is a compile-time option, and this function may therefore not be available.
nav_time_active_set(Integer seconds)  X
This command sets the time tracker for the ship to the specified value. Time tracking is a compile-time option, and this function may therefore not be available.
nav_undock(dbref ship)   
This command attempts to undock the specified object and add it to space. The ST_DOCKED_AT attribute on the ship object should be set to a valid object which is already active in space.
objlist(Integer space, Boolean show_ships, Boolean show_other)   
This command emits a table of space objects which match the selection criteria to the enactor.
owner_number()Integer  X
This function returns the owner number of the specified ship object.
pos()String X 
This function returns a space separated list of the X, Y and Z coordinates of the space object.
range(Dbref target)Integer X 
This function returns the distance from the space object to the target, in the current units used by the space object, or a string starting with #-1 if there was an error.
report_contact(Integer contact) X 
This command causes the specified contact information to be emitted to the enactor. It is a selective form of the contact_list command.
rm_object(dbref object) X 
This command flags the specified object for removal from space. The actual cleanup is done at the end of the next update cycle.
run_cycle(Integer space)   
This command sets the update flag on the space specified, or all spaces if -1 was passed. This optional spacecall is enabled using the turn-based option in spaceconf.h
scan(Integer contact)  X
This command triggers a scan of the specified contact. The contact is scanned if it is within range, and scanners are undamaged.
scanner_status()String status  X
This function returns the status of the scanners. The possible return values are DAMAGED and OK.
sensor_status()String status  X
This function returns the status of the sensors. The possible return values are DAMAGED and OK.
set_consoleflags(Dbref console, String flags)  X
This command sets and clears flags on the given console. To set a flag, just provide the flag name. To clear a flag, add a ! before the name.
set_debug_char(dbref object)   
This command sets the object to which PSE log messages are echoed. It defaults to the GOD character.
set_objflag(String [!]flag) X 
This command sets or clears the specified object flag on the space object. The valid flags are listed in the flags section of the manual.
set_pos(Integer X, Integer Y, Integer Z) X 
This command sets the location of the space object to the given coordinates. The coordinates should be given in universal coordinates, and not range factor adjusted.
set_shipflag(String [!]flag)  X
This command sets or clears the specified ship flag on the space object. The valid flags are listed in the flags section of the manual.
set_torp_ammo(Integer amount)  X
This command sets the number of torpedos/missiles currently loaded on the ship object.
shd_alloc_shield(Integer shield)Integer allocation  X
This function returns the amount of energy currently allocated to the specified shield, or -1 if the shield parameter was not valid for this ship.
shd_allocate(Integer Shd1, Integer Shd2, Integer Shd3, Integer Shd4, Integer Shd5, Integer Shd6)  X
This command allocates the specified amounts of energy to particular shields. If the total allocated is more than the current amount allocated to shields, the specified values are scaled down. On ships with 4 shields, Shd5 and Shd6 should be set to 0.
shd_cloak_off()  X
This command disengages the cloaking device for the ship.
shd_cloak_on()  X
This command attempts to engage a cloaking device for the ship. All the shields must be operational for this to work.
shd_cloak_status()String status  X
This function returns the current status of the cloaking device for the ship object. The possible return values are NONE, OFF, ON, CLOAKING, DECLOAKING.
shd_config_name()String name  X
This function returns the name of the shield configuration on the ship object. It can be one of the following: Type 1 Array (4/PSAF-60), Type 2 Array (6/PSDVAF-60), Type 3 Array (6/PSDVAF-45), Type 4 Array (4/PSVD), Type 5 Array (4/PSVD-45).
shd_full_name(Integer Shield)String name  X
This function returns the full name of the specified shield from the shield array of the ship.
shd_lower_shield(Integer shield)  X
This command lowers the specified shield.
shd_number()Integer shields  X
This function returns the number of shields on the ship. This can vary with the shield configuration selected for the ship.
shd_raise_shield(Integer shield)  X
This command attempts to raise the specified shield. Shields cannot be raised while cloaked, or if the shield is inoperable through damage.
shd_shield_action(Integer shield)String status  X
This function returns the current status of the shield. The return values can be one of STABLE, CHARGE, FALL, OVERLOAD
shd_shield_level(Integer shield)Integer level  X
This function returns the current shield level for the specified shield. If an invalid shield was specified, -1 is returned.
shd_shield_max_level(Integer shield)Integer level  X
This function returns the maximum shield level for the specified shield. If an invalid shield was specified, -1 is returned.
shd_shield_status(Integer shield)String status  X
This function returns the current state of the specified shield. The return values are READY, UP, DAMAGED.
shd_short_name(Integer Shield)String name  X
This function returns the short name of the specified shield from the shield array of the ship.
ship()Boolean X 
This function returns true if the space object is a ship. It returns a string starting with #-1 if the object is not valid.
short_contact_list(Boolean show_ships, Boolean show_other) X 
This command causes the contacts meeting the criteria to be emitted to the enactor in a shorter format than the contact_list spacecall.
space_lock(Integer space, Boolean lock)   
This command sets or clears the lock on the specified space. A locked space cannot have additional space objects added to it without first being unlocked.
space_options()   
This command sends a summary of the compile-time configuration of the Portable Space Engine to the caller.
specs() X 
This command causes the space object specifications, excluding object and ship flags to be emitted to the enactor.
sph_to_xyz(Float bearing, Float elevation, Integer range)Cartesian coordinates   
This function converts the spherical coordinates given into cartesian coordinates, in the order x, y, z.
tac_alloc_guns()Integer alloc  X
This function returns the amount of energy currently allocated to guns. The amount can be changed using the tac_allocate spacecall.
tac_alloc_torps()Integer alloc  X
This function returns the amount of energy currently allocated to torpedoes. The amount can be changed using the tac_allocate spacecall.
tac_alloc_tractor()Integer alloc  X
This function returns the amount of energy currently allocated to the tractor beam. The amount can be changed using the tac_allocate spacecall.
tac_allocate(Integer guns, Integer torps, Integer trator)  X
This command allocates energy to the guns, torpedoes and tractor beam. If the total energy allocated is greater than the total supplied to tactical, the values are scaled down.
tac_auto_charge()  X
This command toggles the setting of torpedo auto-arming. The default setting is disabled.
tac_auto_reload()  X
This command toggles the setting of torpedo auto-reloading. The default setting is enabled.
tac_charge_status()String status  X
This function returns the auto-arming status of the torpedoes. The possible return values are ON and OFF.
tac_fire_gun(Integer gun | all)  X
This command will fire the specified gun, or all guns if the parameter is 'all'. The weapons system must be locked onto a target, and the target must be in range before the guns will fire.
tac_fire_torp(Integer torp | String all, String NONE | Float bearing, String +/-, Float elevation, Integer range)  X
This command will fire the specified torpedo, or all armed torpedoes if the parameter is 'all'. If the second parameter is NONE, the torpedoes will be fired at the currently locked target. If the second parameter is not NONE, the second, third, fourth and fifth parameters are treated as bearing, elevation sign, elevation and range respectively. Torpedoes can only be fired when they are armed, and when the ship is not cloaked.
tac_gun_charge(Integer gun)Integer charge  X
This function returns the amount of charge in the specified gun.
tac_gun_offline(Integer gun)  X
This command takes the specified gun offline. Offline guns cannot be fired or charged.
tac_gun_online(Integer gun)  X
This command brings the specified gun online. Online guns can be fired and charged.
tac_gun_power(Integer gun)Integer power  X
This function returns the maximum charge that the specified gun can be charged with.
tac_gun_qty()Integer quantity  X
This function returns the number of guns available on the ship object.
tac_gun_status(Integer gun)String status  X
This function returns the status of the specified gun. Possible return values are ON, OFF and DAMAGED.
tac_lock(Integer contact)  X
This command attempts to lock weapons on the specified contact. Any existing weapons lock is broken.
tac_lock_status()String status  X
This function returns the current weapons lock status. Possible return values are LOCKED, PENDING and OFF.
tac_reload_status()String status  X
This function returns the auto-loading status of the torpedoes. The possible return values are ON and OFF.
tac_reload_torp(Integer torp)  X
This command starts reloading the specified torpedo if there is a free reloader.
tac_torp_ammo()Integer amount  X
This function returns the number of remaining torpedoes. This is decremented each time a torpedo is fired.
tac_torp_charge(Integer torp)Integer charge  X
This function returns the amount of charge in the specified torpedo. It returns zero if the torpedo is not online or charging.
tac_torp_offline(Integer torp)  X
This command takes the specified torpedo offline. Offline torpedos cannot be armed without first being brought online.
tac_torp_online(Integer torp)  X
This command brings the specified torpedo online. Online torpedos can be armed and fired.
tac_torp_power(Integer torp)Integer power  X
This function returns the total charge needed to arm a torpedo. Torpedos cannot be fired until they are fully charged, and cannot be disarmed. A charged torpedo will expire if it is not fired within a certain time frame.
tac_torp_qty()Integer quantity  X
This function returns the number of torpedo launchers present on the ship object.
tac_torp_status(Integer torp)Integer status  X
This function returns the status of the specified torpedo. The possible return values are EMPTY, RELOADING, LOADED, CHARGING, ARMED and DAMAGED.
tac_tractor_dock()  X
This command attempts to pull the object locked onto with the tractor beam into the docking bay of the ship object making this call. The object must be able to fit through the docking bay doors, facing shields must be lowered, and the docking bay doors must be open.
tac_tractor_draw(Boolean on)  X
This command changes the active state of the tractor beam. With draw mode engaged, the tractored object is drawn towards the ship.
tac_tractor_lock(Integer contact)  X
This command attempts to lock the tractor beam onto the specified target. The target must be within range, and set TRACTORABLE. The maximum tractor beam range is equivalent to the amount of power allocated to the beam. Any existing tractor lock is broken, and the EV_TRACTOR_* events are triggered.
tac_tractor_status()String status  X
This function returns the current tractor beam status. Possible return values are NONE, ON, OFF, DRAW, and DAMAGED.
tac_tractor_target()Integer contact  X
This function returns the contact number of the tractored object, if any. An emptry string is returned if no object is being tractored.
tac_tractor_unlock()  X
This command unlocks the tractor beam from it's current target, if any.
tac_unlock()  X
This command unlocks the weapon systems from the current target, if any.
trans_list_beamable()String list X 
This function returns a list of the objects on the contact list which have the BEAMABLE flag set. This could be set on a space object representing an escape pod, for instance.
trans_list_dests()String list X 
This function returns a list of the objects on the contact list which have the CAN_BEAM_TO flag set.
trans_permission(dbref target)String permission X 
This function returns a string indicating the validity of a transport from the space object to the target. It returns: OK, INVALID SOURCE, INVALID TARGET, SOURCE SHIELD, TARGET SHIELD, OUT OF RANGE, or DAMAGED.
warp_cost(Float warp)Integer cost  X
This function returns the amount of energy required by the ship to achieve the specified speed. It accounts for the SPEEDY and POKEY flags being set, but does allow speeds greater than the maximum to be speficied.
warp_table()  X
This command causes a table of warp speeds between warp 1 and warp 10 to be emitted to the enactor, along with the energy requirements for each speed.
write_all_objects(Int Space)   
This command updates the attributes on all of the space objects in the given space. It can be called periodically to keep the state of the server database synchronized with the Portable Space Engine state. Normally this is only done when an object is added or removed from space for efficiency reasons.
write_object() X 
This command updates the attributes on the space object. It can be called periodically to keep the state of the server database synchronized with the Portable Space Engine state. Normally this is only done when an object is added or removed from space for efficiency reasons.
xyz_to_sph(Integer x, Integer y, Integer z)Spherical coordinates   
This function converts the cartesian coordinates given to spherical coordinates, in the order Bearing, Elevation, Range. Bearing is between 0 and 360 degrees, and elevation between +90 and -90 degrees.


Last modified: 15th March 1998