User:Oggal/Sandbox

Custom Stories

Custom stores can be created in any text editor. They require at minimum 2 story blocks, the catalyst and one other. They can contain any number of blocks.

Functions

Story Functions

Story functions configure the current story. Most story functions can only be used in the catalyst block. The only exception is the 'storyDroppable' function.

Story Functions

Method Name	Arguments	Description	Return
storyTitle	text
storyAuthor	text	Identifies the author of the story. Required in catalyst block.
storyAutoRepeat		Enables the story to automatically start repeatedly, based on the catalyst. The story can restart within 10 seconds of being terminated if an interval is not specified. Only one auto started story can be active at a time.
storyAutoRepeatUntilComplete	int	Enables the story to automatically start repeatedly, based on the catalyst. The story can restart within 10 seconds of being terminated if an interval is not specified.The story stops autostarting once it has been completed. A story that is dropped is not considered to be completed. Only one auto started story can be active at a time.
storyAutoStart		Enables the story to automatically start once, based on the catalyst. Only one auto started story can be active at a time.
storyBrief	text	Gives a brief description of the story. Required in catalyst block.
storyDroppable	bool	Sets the current story's droppable state. The droppable state of a story can be changed at any time in the script. A story that is not droppable cannot be canceled by the avatar using the Jobs window. The avatar gets a thought message if they try dropping an undroppable story. Usually, avatars must be able to drop a story to enable it to restart. Disable drop only when dropping would break the story in some way.
storyInterval	int	Specifies the time interval in minutes before the story can start again. The time interval starts when the story terminates, whether by finishing or by dropping.
storyResultText	int,text	Declares the text that explains a result code set by avatarStoryResult.

Avatar Functions

Avatar functions operate on the avatar atom for whom the story is running.

Avatar Functions

Method Name	Arguments	Description	Return
avatar		Returns the person executing the story.
avatarConstructedIndustryHabitable		Test if the person has ever constructed a particular industry on a habitable world. True is returned if they ever planned one, regardless of whether it was completed.
avatarConstructedIndustryHarsh		Test if the person has ever constructed a particular industry on a world with a harsh environment. True is returned if they ever planned one, regardless of whether it was completed.
avatarCreditAccount	real	Adds a number of cronodollars to the person's account.
avatarCurrentItem	commodity	Test if the person's current item is a commodity.
avatarDebitAccount	real	Subtracts a number of cronodollars from the person's account.
avatarEnvironment		Returns the environment atom that contains the person. This is usually a solar system but it can be an arena or a design studio. The environment containing the person is the only environment a story can access.	atom
avatarEVAMinutes		Returns the number of minutes of EVA experience.
avatarHadItem	commodity	Test if the person's gear has ever contained a commodity.
avatarHasFood		Test if the person's gear contains any food.
avatarHasItem	commodity	Test if the person's gear contains a commodity.
avatarHasItemInHand	commodity	Test if the person is holding a commodity in their hand.
avatarHasItemInHandSpecific	commodity,quality,empire,text	Test if the person is holding a specific commodity in their hand. 'text' is compared against the inscription only if 'text' is not blank.
avatarHasItemSpecific	commodity,quality,empire,text	Test if the person's gear contains a very specific commodity. 'text' is compared against the inscription only if 'text' is not blank.
avatarHasPreon		Test if the person's gear contains any kind of preon. Also checks inside the ship the person is aboard; checks both cargo and items lying about that are not on static display. Also checks in the vehicle the person is aboard, if any.
avatarInCity		Test if the person is in a city. The person must be standing in a developed terrain tile.
avatarInitScenario	scenario	Test if the person started the game using a specified 'scenario'.
avatarInOrbit		Test if the person is in orbit at a planet, outside the atmosphere.
avatarInStudio		Test if the person is inside a design studio instance.
avatarInVehicle		Test if the person is inside a certain type of vehicle.
avatarInVehicleMoving		Test if the person is inside a certain type of vehicle that is moving.
avatarInVehicleOnGround		Test if the person is inside a certain type of vehicle that is touching the ground.
avatarItemCount	commodity	Returns the amount of a commodity possessed by the avatar.
avatarItemMakePermanent	commodity,quality,empire,text	Makes permanent a specific item in the person's gear. Permanent story items persist in the game after the story ends. Nonpermanent story items are removed from the game when the story ends. Arguments: 'text' is compared against the inscription only if 'text' is not blank.
avatarItemSetDropOnDeath	int,commodity,quality,empire,text	Sets the 'drop' behavior of an item: 0=default random drop on death, 1=no drop, 2=always drop. 'bool' is the new state.
avatarLineageAvatar		Returns true if the avatar's lineage is a regular avatar.
avatarLineageDemiavatar		Returns true if the avatar's lineage is demiavatar.
avatarLineageHighborn		Returns true if the avatar's lineage is highborn.
avatarOnLineMinutes		Returns number of minutes the person has been on line.
avatarRecallNpcWorld	text [this assumption is unchecked]	Returns the world on which an npc was last seen. Arguments: 'text' is the name of the npc.	world
avatarStoryCompleted		Test if the person has completed a particular story script id.
avatarStoryCompletedMinutes		Returns the number of minutes since a story was completed. Returns -1 if the story was never completed.
avatarStoryLastResult		Returns a result code associated with a particular story script id. A result code of 0 to 255 indicates the avatar has run the script. -1 is returned if the story has never been started.
avatarStoryResult	int	"Stores the result for the current story in an avatar's memory. 'int' is result, in the range 0 to 255.
avatarTraversedStargate		Test if the avatar has ever been aboard a spacecraft that traversed a stargate.
avatarVehicleMinutes		Returns number of minutes the person has experience in a vehicle.

Miscellaneous / Control Flow

Miscellaneous / Control Flow

Method Name	Arguments	Description	Return
NOP		No operation.
CONST		Constant value.
VAR		Variable.
&&		Logical AND.
||		Logical OR.
==		Equality test.
<=		Less than or equal test.
<		Less than test.
>=		Greater than or equal test.
>		Greater than test.
goto	void	Unconditional branch to a block of the story.	void
if	bool	In the catalyst block, 'if' tests determine when the story can start for an avatar and which block will begin the story. In body blocks, 'if' tests determine when to branch to another block of the story. Each block of the story, including the catalyst, may contain more than one 'if' to test and branch based on different conditions. The story engine checks the 'if' conditions of the current block every 10 seconds. Each 'if' is tested in the order it appears in the script. The first 'if' to return true results in a branch to its block of the story.	void
choiceMade		Test for selection of a specific choice that was offered using a choice command on a comm channel.	choiceValue
dateIsChristmas		Test if the current date is Christmas eve or Christmas day. Returns true on 12/24 and 12/25.	bool
wait	int	Returns true if 'int' seconds or more have passed since the current story block was started.	bool

Atom Functions

Atom functions operate on a specific atom, which is the first argument of most atom functions. When the 'atom' argument is not valid, all functions return quietly.

Atom Functions

Method Name	Arguments	Description	Return
atom	int	Casts 'int' to be an atom identifier.	atom
atomCity	atom	Returns the city capitol building atom whose jurisdiction controls the building site that contains 'atom'. The result is 0 if the atom's current building is not part of a city. If 'atom' is on a road, the capitol building whose jurisdiction contains 'atom' is returned. The result is 0 if 'atom' is not at a building site or on a road in a city.	city
atomComm	atom,channel,range,text	Atom sends a message on a comm channel.	void
atomCommChannelToAtom	atom,atom,channel	Atom opens a channel to the other atom.	void
atomCommChoice	atom,channel,range,choiceValue,text	Atom says a choice on a comm channel. A choice message appears with a bright green asterisk. Several choices may be stated if each is given a different choiceValue. Result of player's choice is tested using the choiceMade function.	void
atomCreateNpc	atom,angle,real,text,gender,hand,empire,dna,stage,bool	Creates an npc near 'atom', subordinate to the same parent as 'atom'. Will not create the character if 'atom' is in a vehicle. Arguments: 'angle' is relative to the atom's facing: 0 is forward, 90 is left, -90 is right and 180 is behind. 'real' is a distance in meters. The new npc's location will be in the domain of 'atom's parent. The path from 'atom' to the new npc's location will be unobstructed. The final starting location will be no farther than 'real' meters from 'atom', even if it means starting on top of 'atom'. 'text' is the name of the new npc. If a npc with the same name and story instance exists in the environment, it is moved rather than create a new npc. 'dna' specifies the DNA of the npc. However, if the avatar of the story has ever met a story npc with the same name, in any prior encounter, then the 'dna' argument is overridden by the DNA of the original npc met by the avatar. 'stage' specifies the growth stage of the npc. 'bool' specifies the visibility of the npc.	npc
atomDistanceToAtom	atom,atom	Returns the distance between two atoms, in meters.	real
atomEmpire	atom	Returns id value of an atom's empire. 0 if none.	int
atomFindIndustry	atom,industry,int,stance,int	Locates a building of a specific 'industry' type, subordinate to 'atom'. Arguments: 'int' is under construction requirement: 0=yes, 1=no, 2=ok. 'stance' and 'int' are used to check the atom empire's stance toward the building's empire. 'int': 0=stance must match, 1=stance must match or be better, 2=stance must match or be worse.	atom
atomFindIndustryAtmosphere	atom,industry,int,stance,int,atmosphere	Locates a building of a specific 'industry' type, subordinate to 'atom'. The building must be on a world with a specific 'atmosphere'. Arguments: 'int' is under construction requirement: 0=yes, 1=no, 2=ok. 'stance' and 'int' are used to check the atom empire's stance toward the building's empire. 'int': 0=stance must match, 1=stance must match or be better, 2=stance must match or be worse.	atom
atomFindVehicle	atom,commodity,int	Locates a vehicle of a specific 'commodity' type, subordinate to 'atom'. 'int' is 1 if the vehicle must be new, 2 if the vehicle must not be new, and 0 if you don't care.	vehicle
atomHasAtom	atom,atom	Searches the atom recursively for an atom. Returns true if the atom is found.	bool
atomHasIndustry	atom,industry,int,stance,int	Test recursively if an atom has a building of a particular industry type. The atom might typically be a system, world or city. Arguments: 'int' is under construction requirement: 0=yes, 1=no, 2=ok. 'stance' and 'int' are used to check the atom empire's stance toward the building's empire. 'int': 0=stance must match, 1=stance must match or be better, 2=stance must match or be worse.	bool
atomInAtmosphere	atom	Returns true if atom is inside the atmosphere of a world, regardless if there is any air density.	bool
atomInSystem	atom,system	Returns true if atom is in a solar system.	bool
atomIsAtom	atom,atom	Returns true if atom == atom and atom is valid.	bool
atomOnGround	atom	Returns true if atom is on the ground.	bool
atomSector	atom	Returns the sector atom that contains 'atom'.	sector
atomShip	atom	Returns the spacecraft atom that contains 'atom'. Starts the search at 'atom's parent. 'atom' will not be returned by this function if it is a spacecraft.	ship
atomSystem	atom	Returns the solar system atom that contains 'atom'.	system
atomValid	atom	Returns true if the atom exists and looks valid. The atom must be a galaxy, sector, the current solar system, design studio or arena, or it must be in the same solar system, design studio, or arena as the avatar.	bool
atomVehicle	atom	Returns the vehicle atom that contains 'atom'. Starts the search at 'atom's parent. 'atom' will not be returned by this function if it is a vehicle.	vehicle
atomWorld	atom	Returns the world atom that contains 'atom'. 'atom' may be subordinate to the world at any subatom level or distance, possibly in space. Returns 'atom' if atom is a world.	world
atomWorldLL	atom	Returns the longitude latitude of an atom, if it is on a world.	ll

---

Blueprint Functions

Atoms may reference blueprints but blueprints are not atoms by themselves. i.e. a building atom references a building blueprint to know about its geometry and other design features.

Blueprint Functions

Method Name	Arguments	Description	Return
blueprintSpacecraftLoad	sc	Test if the spacecraft design is loaded. Signals the need for it to be loaded, if it is not already loaded.	bool

---

City Functions

City functions operate on a capitol building atom.

CityFunctions

Method Name	Arguments	Description	Return
cityFindNewVehicle	city,commodity	Returns a new vehicle in a city, at a factory that makes them.	vehicle
cityHasIndustry	city,industry,int	Test if a city has a number of completed levels of an industry, as shown on the city report. Levels are shops, fields, generators, etc. as appropriate to the industry.	bool
cityHasFood	city	Test if a city has any food in any of its buildings.	bool
cityHasItem	city,commodity	Test if a city has a commodity in any of its buildings. Vehicle commodities return true if a new vehicle is found at a factory that makes them.	bool
cityHasPower	city	Test if a city has any electricity. Arguments: 'city' can be any building.	bool
cityItemCount	city,commodity	Returns the total amount of a commodity in a city's inventory. Does not count vehicles.	int
cityPopulation	city	Returns the population of a city.	int

---

Creature Functions

Creature functions operate on a specific creature, which is the first argument of all creature functions.

Creature Functions

Method Name	Arguments	Description	Return
creatureDismountVehicle	creature	Creature exits the vehicle it occupies.	void
creatureIsDyingOrDead	creature	Test if the creature's body is dying or dead.	bool
creatureSetHealth	creature,int	Sets health level of a creature. Arguments: 'int' is the health level as a percentage, 0 to 100.	void
creatureSetMouth	creature,visage,visage	Sets 'visage' pose of a creature. When the first 'visage' pose is an animated pose, the second 'visage' pose is set when the animation completes.	void
creatureSetVisage	creature,visage	Sets 'visage' of a creature.	void

---

Find Functions

Find functions operate in the avatar's current environment. The environment is the solar system, design studio instance, or arena instance that contains the avatar.

| Method Name | Inputs | Description | Return Type | |---|---|---|---| | findGasGiant | orbit | Locates a gas giant in the current environment. Avatar must not be in deep space.

Arguments:
'orbit' may include the also types. | world | | findMoon | orbit | Locates a moon in the current environment. Avatar must not be in deep space.

Arguments:
'orbit' may include the also types. | world | | findPlanetAtmosphere | atmosphere,int | Locates a planet in the current environment with a specific atmosphere. Avatar must not be in deep space.

Arguments:
'atmosphere' may include the also types.
'int' is maximum hydrographics percentage in the range 0 to 100. | world | | findPlanetOrbit | orbit,int | Locates a planet in the current environment. Avatar must not be in deep space.

Arguments:
'orbit' may include the also types.
'int' is maximum hydrographics percentage in the range 0 to 100. | world | | findRing | orbit | Locates a ring around a world in the current environment. Avatar must not be in deep space.

Arguments:
'orbit' may include the also types. | world | | findRingworld | | Locates a ringworld arc section in the current environment. Avatar must not be in deep space. | world | | findSectorWithNeutronStar | int | Locates a sector that contains a neutron star. Searches outward from the current environment's sector.

Arguments:
'int' is maximum range in sectors to search. | sector | | findSectorWithRingworld | int | Locates a sector that contains a ringworld. Searches outward from the current environment's sector.

Arguments:
'int' is maximum range in sectors to search. | sector | | findSectorWithStellarBlackHole | int | Locates a sector that contains a stellar black hole. Searches outward from the current environment's sector.

Arguments:
'int' is maximum range in sectors to search. | sector | | findVehicleNearby | atom,commodity,empire,real | Finds a vehicle within 'real' distance of an atom. | vehicle |

---

Henge Functions

Henge functions operate on the henges that interconnect ringworld arc sections with other worlds in the ringworld's sector.

| Method Name | Inputs | Description | Return Type | |---|---|---|---| | hengeSystemName | system | Returns the name of a solar system that is known to contain a henge, as returned by the 'sectorHengeSystem' function. | text | | hengeSystemWorld | system,int | Returns the catalog name of a habitable world that contains a henge portal, if any. The henge portal will be more than 200m from any city.

Arguments:
'int' is henge type: 0=any, 1=on globe, 2=on ringworld. | worldcat | | hengeWorld | worldcat | Returns the world id of a henge world, given its catalog name. Story avatar must be in the solar system with the world.

Arguments:
'worldcat' is a catalog name of a henge world. | world | | hengeWorldConnection | world | Returns the world to which a world is connected by henge portal. The portal does not have to be active.

Arguments:
'world' is a world known to have a henge. | world | | hengeWorldLL | worldcat | Returns the longitude latitude of a henge if there is one.

Arguments:
'worldcat' is a catalog name of a henge world. | ll | | hengeWorldName | worldcat | Returns the name assigned to a henge world, given its catalog name. | text | | hengeWorldPortalActive | worldcat,ll | Test if the henge portal on a world is active. An active portal is indicated when the henge fire turns blue.

Arguments:
'worldcat' is a catalog name of a henge world. | bool |

---

Item Functions

An item atom represents a commodity in the environment. Once it is picked up by anybody, the item atom ceases to exist and the item's data is added to their gear. A new atom is created when that item, or any item, is dropped in the environment.

| Method Name | Inputs | Description | Return Type | |---|---|---|---| | itemArmWeapon | item,unit,empire | Arms a weapon, if the item is a weapon that can be armed. e.g. Plastic Explosive.

Arguments:
'unit' is the unit who armed the weapon.
'empire' is the empire who armed the weapon. | void | | itemCreateContent | item,bool,int,commodity,quality,empire,text | Creates a new item inside 'item', which is expected to be a container.

Arguments:
'bool' is true to make the item permanent. Permanent story items persist in the game after the story ends. Nonpermanent story items are removed when the story ends.
'empire' is the empire of origin of the item.
'int' is condition percent, 1 to 100.
If 'text' is not blank, it is inscribed onto the item. | void | | itemDetonate | item | Detonates an armed weapon, if the item is a weapon that is armed. e.g. Plastic Explosive. Other items disappear quietly. | void | | itemMakePermanent | item | Changes a story item into a permanent item.

Permanent story items persist in the game after the story ends. Nonpermanent story items are removed when the story ends. | void | | itemOnGround | commodity,real | Locates an item on the ground nearby.

Arguments:
'real' is the farthest distance from the story avatar to find the item, in meters. | item | | itemOnGroundSpecific | int,commodity,quality,empire,text | Locates a specific item on the ground nearby.

Arguments:
'int' is the farthest distance from the story avatar to find the item, in meters.
'text' is compared against the inscription only if 'text' is not blank. | item | | itemSetDropOnDeath | item,int | Sets the drop behavior of an item: 0=default random drop on death, 1=no drop, 2=always drop.

Arguments:
'int' is the new state. | void | | itemSetMessage | item,text | Sets the message of an item, such as a beacon. This is not the inscription.

Arguments:
'text' is the new message. | void | | itemSetState | item,int | Sets the state of an item, such as the on/off state of a light or musical instrument.

Arguments:
'int' is the new state. | void |

---

Narrator Functions

Narrator communications are associated with the story itself and do not emanate from any in-game source.

| Method Name | Inputs | Description | Return Type | |---|---|---|---| | narratorHint | text | Sends a text message on the narrator comm channel when requested by the person. Hints are requested using the ? button on the Jobs window. | void | | narratorImage | file,text,text | Sends a picture, a title, and an optional message on the narrator comm channel. The image appears automatically in a popup window. | void | | narratorSay | text | Sends a text message on the narrator comm channel. | void | | narratorSayAudio | file,text | Sends audio and an optional text message on the narrator comm channel. | void | | narratorSayChoice | choiceValue,text | Say a choice on the narrator comm channel. A choice message appears with a bright green asterisk.

Several choices may be stated if each is given a different choiceValue.

Result of player's choice is tested using the choiceMade function. | void | | narratorTitle | text | Sends a text message on the narrator comm channel formatted as a title. | void | | narratorVideo | file,text | Sends video and an optional text message on the narrator comm channel. | void |

---

Npc Functions

Npc's are AI controlled citizens not including demiavatars who are AI controlled.

Caption text

Method Name	Inputs	Description	Return Type
npcCreditAccount	npc,real	Adds a number of cronodollars to the npc's account.	void
npcDebitAccount	npc,real	Subtracts a number of cronodollars from the npc's account.	void
npcDepart	npc	Causes an npc to depart the scene. The npc disappears instantly with no visual effect.	void
npcDie	npc	Kills an npc. They fall to the ground and die like other sentient creatures. Their body dies of massive internal injuries with no bleed out time.	void
npcEquipFromCity	npc,gearslot,commodity,text	Transfer an item to an npc's gear from the inventory of the current city. Arguments: 'text' is an optional inscription to place on the item. Quietly does nothing if the npc already has an item in that slot.	void
npcSetIndestructible	npc,bool	Sets indestructible state of an npc.	void
npcSetRole	npc,npcrole	Changes the role of an npc. The role of an npc cannot be changed while they hold a berth.	void
npcSetVisible	npc,bool	Changes the visibility of an npc.	void
npcWantItem	npc,commodity	Causes the npc to want a specific commodity. When an npc wants an item, they will make a bid if it is offered on the voice channel.	void
npcWantItemPrice	npc,commodity,int,int	Causes the npc to want a specific commodity at a specific price per unit. When an npc wants an item, they will make a bid if it is offered on the voice channel. Arguments: First 'int' is the maximum number of the items wanted. 0 means no limit. Second 'int' is price per unit. May be 0.	void
npcWantItemSpecific	npc,commodity,quality,empire,text,int,int	Causes the npc to want a very specific commodity. When an npc wants an item, they will make a bid if it is offered on the voice channel. Arguments: 'text' is compared against the inscription only if 'text' is not blank. First 'int' is the maximum number of the items wanted. 0 means no limit. Second 'int' is price per unit. May be 0.	void
npcWantOfferMade	npc	Test if the npc has made an offer to buy an item it wants that was offered for sale.	bool

---

Ringworld Functions

Ringworld functions operate on a specific ringworld arc section.

| Method Name | Inputs | Description | Return Type | |---|---|---|---| | ringworldControlCenter | world | Returns the ringworld arc section that contains the control center for a world that is also a ringworld arc section.

Arguments:
'world' is a ringworld arc section. | world | | ringworldControlCenterLL | world | Returns the longitude and latitude of the control center on a ringworld arc section. Currently this is always at 0 0.

Arguments:
'world' is a ringworld arc section known to contain a control center. | ll | | ringworldIsControlCenterActive | world | Returns true if the ringworld is active with an open stargate.

Arguments:
'world' is a ringworld arc section. | bool | | ringworldIsStargateBeamBlocked | world | Returns true if the ringworld shadow panels block the stargate beams, preventing activation of a stargate.

Arguments:
'world' is a ringworld arc section. | bool |

---

Sector Functions

Sector functions operate on a specific sector, which is the first argument of all sector functions.

| Method Name | Inputs | Description | Return Type | |---|---|---|---| | sectorHasHengeSystem | sector,int | Test if the sector contains a habitable world with a henge portal. The henge portal will be more than 200m from any city.

Arguments:
'int' is henge type: 0=any, 1=on globe, 2=on ringworld. | bool | | sectorHengeSystem | sector,int | Returns a solar system that contains a habitable world with a henge portal, if any. The henge portal will be more than 200m from any city.

If more than one of them exists, one is chosen randomly. Ringworld systems are not returned even though they always contain henge portals.

Arguments:
'int' is henge type: 0=any, 1=on globe, 2=on ringworld. | system |

---

Sentient Functions

Sentient functions operate on a specific sentient creature, which is the first argument of all sentient functions.

| Method Name | Inputs | Description | Return Type | |---|---|---|---| | sentientAttackUnit | sentient,unit | Order a sentient to attack a unit. | void | | sentientClearGear | sentient | Removes all items of gear. | void | | sentientCreateGear | sentient,gearslot,bool,commodity,quality,empire,text | Create an item in a sentient's gear.

Arguments:
'bool' is true to make the item permanent. Permanent story items persist in the game after the story ends. Nonpermanent story items are removed when the story ends.
'empire' is the empire of origin of the item.
'text' is inscribed on the item if not blank. If the item is a blueprint disk or drawing, the inscription can be used to pass the blueprint id. | void | | sentientDropGear | sentient,gearslot | Drops the item at a sentient's gear slot. | item | | sentientDropGearItem | sentient,commodity | Drops an item from a sentient's gear. | item | | sentientFireWeapon | sentient | Order a sentient to fire their weapon in hand at nothing in particular. | void | | sentientFollowAvatar | sentient | Order a sentient to follow the person. | void | | sentientFollowSentient | sentient,sentient | Order a sentient to follow another sentient. | void | | sentientGetIn | sentient,atom | Sentient moves close enough then rides the unit. e.g. boards a vehicle or spacecraft or rides a horse. | void | | sentientGetItem | sentient,item | Order a sentient to pick an item up off the ground. | void | | sentientGetOut | sentient,atom | Sentient gets out of an atom. Completed when atom is no longer their parent. If an active teleporter is present, they will get into it. | void | | sentientGoToAvatar | sentient | Order a sentient to go to the avatar. | void | | sentientGoToLL | sentient,ll | Order a sentient to go to a longitude latitude. | void | | sentientGoToLLExactly | sentient,ll | Order a sentient to go to a longitude latitude as precisely as possible. | void | | sentientGoToRoom | sentient,text | Order a sentient to go to a room, by room name. The sentient needs to be aboard a spacecraft. | void | | sentientGoToUnit | sentient,unit | Order a sentient to go to a unit. | void | | sentientHasItem | sentient,commodity | Test if the sentient possesses a specific commodity. | bool | | sentientHasItemSpecific | sentient,commodity,quality,empire,text | Test if the sentient's gear contains a very specific commodity.

Arguments:
'text' is compared against the inscription only if 'text' is not blank. | bool | | sentientHengeCeremony | sentient,ll | Order a sentient to perform the henge ceremony, if a henge is found near 'll'. | void | | sentientItemMakePermanent | sentient,commodity,quality,empire,text | Makes permanent a specific item in the sentient's gear. Permanent story items persist in the game after the story ends. Nonpermanent story items are removed when the story ends.

Arguments:
'text' is compared against the inscription only if 'text' is not blank. | void | | sentientItemSetDropOnDeath | sentient,int,commodity,quality,empire,text | Sets the drop behavior of an item in a sentient's gear: 0=default random drop on death, 1=no drop, 2=always drop.

Arguments:
'int' is the new state. | void | | sentientItemSetState | sentient,int,commodity,quality,empire,text | Sets the state of an item in a sentient's gear, such as the on/off state of a light or musical instrument. Nothing happens if the item does not support different states.

Arguments:
'int' is the new state. Valid values are in the range of 0 to 255. | void | | sentientMoveAway | sentient,atom,real,real | Order a sentient to move away from 'atom'.

Arguments:
First 'real' is the distance to move in meters.
Second 'real' is the angle left or right from directly away in degrees. | void | | sentientMoveBack | sentient,real | Order a sentient to move backward a distance specified in meters. | void | | sentientMoveClose | sentient,atom,real | Order a sentient to move close to atom, within a distance specified in meters. | void | | sentientMoveForward | sentient,real | Order a sentient to move forward a distance specified in meters. | void | | sentientMoveToward | sentient,atom,real | Order a sentient to move toward 'atom'.

Arguments:
First 'real' is the distance to move in meters. Distance is truncated to the current distance to the atom.
Second 'real' is the angle left or right from directly toward in degrees. | void | | sentientOkToRun | sentient,bool | Sets whether a sentient is permitted to run to their destination. Default is yes. | void | | sentientReload | sentient,itemsub,commodity,quality,empire,text | Order a sentient to reload their weapon. | void | | sentientSay | sentient,text,visage | Order a sentient being to say a message on the Voice channel.

Arguments:
'visage' is the mouth pose after speaking, may be None to leave it as is. | void | | sentientSayAudio | sentient,file,text,visage | Order a sentient to say a message on the Voice channel. The audio emits from the sentient.

Arguments:
'visage' is the mouth pose after speaking, may be None to leave it as is. | void | | sentientSayChoice | sentient,choiceValue,text,visage | Order a sentient being to say a choice on the Voice channel. A choice message appears with a bright green asterisk.

Several choices may be stated if each is given a different choiceValue.

Result of player's choice is tested using the choiceMade function.

Arguments:
'visage' is the mouth pose after speaking, may be None to leave it as is. | void | | sentientSayImage | sentient,file,text,text,visage | Order a sentient to say a message on the Voice channel. The image appears automatically.

Arguments:
'text' args are image title and text to say.
'visage' is the mouth pose after speaking, may be None to leave it as is. | void | | sentientSayTo | sentient,atom,text,visage | Order a sentient being to say a message on the Voice channel to someone. They will turn to face them.

Arguments:
'visage' is the mouth pose after speaking, may be None to leave it as is. | void | | sentientSellGearItem | sentient,atom,commodity,int | Offers an item from a sentient's gear on the Voice channel.

Arguments:
'atom' is the target of the sale, causing sentient to turn to face them; it can be null.
The best Q 'commodity' possessed by 'sentient' is offered for sale.
'int' is the price, which can be 0 to offer it for free. | void | | sentientSetPosture | sentient,posture | Order a sentient to assume a posture. | void | | sentientStay | sentient | Order a sentient to stay at their current location. | void |

---

Ship Functions

Ship functions operate on a specific spacecraft, which is the first argument of all ship functions.

| Method Name | Inputs | Description | Return Type | |---|---|---|---| | shipChargeCapacitor || ship || Fills the capacitor to 100% on a ship. || void | | shipChargeShields | ship | Fills the shields to 100% on a ship. | void | | shipCreateCrew | ship,dna | Fills all empty crew positions on a ship. Creates regular crew not associated with a story instance.

Arguments:
'dna' is used to create the new crew members. | void | | shipCreateNpc | ship,int,text,gender,hand,empire,dna,stage,bool | Creates an npc aboard 'ship'.

Arguments:
'int' is placement strategy: 0=transporter void location, 1=crew or troop void location, 2=colonist void location.
'text' is the name of the new npc. If an npc with the same name and story instance exists in the environment, it is moved rather than create a new npc.
'dna' specifies the DNA of the npc. However, if the avatar of the story has ever met a story npc with the same name, in any prior encounter, then the 'dna' argument is overridden by the DNA of the original npc met by the avatar.
'stage' specifies the growth stage of the npc.
'bool' specifies the visibility of the npc. | npc | | shipCreateTroops | ship,dna | Fills all empty troop positions on a ship. Creates regular troops not associated with a story instance.

Arguments:
'dna' is used to create the new troops. | void | | shipFindAI | ship,npcrole | Locates an AI controlled sentient aboard a ship.

The returned sentient will be an NPC or a demiavatar who is offline and AI controlled. The sentient will not be at a station or post; use shipStationOccupant to find them. | sentient | | shipFindAIInRoom | ship,npcrole,text | Locates an AI controlled sentient aboard a ship, in a specific room.

The returned sentient will be an NPC or a demiavatar who is offline and AI controlled. The sentient will not be at a station or post; use shipStationOccupant to find them.

Arguments:
'text' is the room name to search, as returned by unitRoomName. | sentient | | shipFindNpc | ship,npcrole | Locates an npc aboard a ship. Does not find demiavatars. | npc | | shipFindNpcInRoom | ship,npcrole,text | Locates an npc aboard a ship, in a specific room. Does not find demiavatars.

Arguments:
'text' is the room name to search, as returned by unitRoomName. | npc | | shipHasCargo | commodity | Checks for a commodity in the hold of a spacecraft. | bool | | shipInteriorLight | ship,int | Sets a ship's interior light state. 0=off, 1=on, 2=dim. | void | | shipManeuverDrive | ship,int | Sets a ship's maneuver drive state. 0=off, 1=on, 2=hold. | void | | shipPowerPlant | ship,int | Sets a ship's power plant state. 0=off, 1=on. | void | | shipRefuel | ship,int | Fills the fuel cells to 100% on a ship with 'int' quality fuel. | void | | shipRetreat | ship | Ship selects a random solar system and goes directly there at maximum speed, without using wormholes. This is an exit-the-scene maneuver. | void | | shipShields | ship,int | Sets a ship's shield state. 0=off, 1=on. | void | | shipStationOccupant | ship,station | Returns a creature who is controlling or occupying a station on the ship.

When multiple redundant stations exist, the sentient currently controlling the underlying system is returned. e.g. when two helms exist the active pilot is returned.

Unless otherwise noted here, the returned creature will be an NPC or a demiavatar who is offline and AI controlled.

Command station prefers to return the AI officer with the con. If none is found, any AI officer is returned.

Designer returns an avatar in a designer instance.

Livestock returns an animal. | creature | | shipStationOccupantInRoom | ship,station,text | Returns a creature who is controlling or occupying a station on the ship, in a specific room.

When multiple redundant stations exist, the sentient currently controlling the underlying system is returned.

Unless otherwise noted here, the returned creature will be an NPC or a demiavatar who is offline and AI controlled.

Command station prefers to return the AI officer with the con. If none is found, any AI officer is returned.

Designer returns an avatar in a designer instance.

Livestock returns an animal.

Arguments:
'text' is the room name to search, as returned by unitRoomName. | creature |

---

Unit Functions

A unit is any creature, vehicle, or spacecraft.

| Method Name | Inputs | Description | Return Type | |---|---|---|---| | unitAboardShip | unit | Returns the ship that the unit is aboard, could be on the hull or hanging from a ladder. | ship | | unitAirBreathable | unit | Test for breathable air at the unit's location. True inside pressure tents and buildings. | bool | | unitAtIndustry | unit,industry | Test for presence of a unit at a particular industry site. Does not have to be inside the building. | bool | | unitInOrbit | unit | Test if the unit is in orbit at a planet, outside the atmosphere. | bool | | unitInsideShip | unit | Returns the ship that the unit is inside. The unit must be in a room, not on the hull or hanging from a ladder. | ship | | unitIsNew | unit | Test if the unit is new and unused. This test only really applies to vehicles and spacecraft. All other units return false. | bool | | unitRoomName | unit | Returns the name of the room that the unit is inside. The room may be in a ship or in a building. Blank is returned when the unit is not inside a room. | text | | unitStationInTradeRange | unit,stance,int | Returns station that is within trade range of the unit. Fleet ship locked in formation passes the question on to its flagship.

Arguments:
'stance' and 'int' are used to check the station empire's stance toward the unit's empire. 'int': 0=stance must match, 1=stance must match or be better, 2=stance must match or be worse. | ship |

---

Vehicle Functions

Vehicle functions operate on a specific vehicle, which is the first argument of all vehicle functions.

| Method Name | Inputs | Description | Return Type | |---|---|---|---| | vehicleCreateNpc | vehicle,int,text,gender,hand,empire,dna,stage,bool | Creates an npc aboard 'vehicle'.

Arguments:
'int' is seat index, -1 for first empty seat.
'text' is the name of the new npc. If an npc with the same name and story instance exists in the environment, it is moved rather than create a new npc.
'dna' specifies the DNA of the npc. However, if the avatar of the story has ever met a story npc with the same name, in any prior encounter, then the 'dna' argument is overridden by the DNA of the original npc met by the avatar.
'stage' specifies the growth stage of the npc.
'bool' specifies the visibility of the npc. | npc | | vehicleRefuel | vehicle | Fills the fuel cells to 100% on a vehicle. | void | | vehicleSetThrottle | vehicle,int | Sets the throttle on a vehicle. | void | | vehicleSwitchEngine | vehicle,bool | Turns the engine on or off. | void | | vehicleSwitchLight | vehicle,bool | Turns the light on or off. | void |

---

World Functions

World functions operate on a specific world, which is the first argument of all world functions.

| Method Name | Inputs | Description | Return Type | |---|---|---|---| | worldAtmosphere | world,atmosphere | Test if the world atmosphere matches 'atmosphere'. | bool | | worldClaimed | world | Test if the world is claimed by any empire. | bool | | worldClaimedBy | world,empire | Test if the world is claimed by 'empire'. | bool | | worldCreateIndigenous | world,ll,dna | Create an indigenous village on a world. Establishes the indigenous DNA using 'dna' if it is not already set. | void | | worldCreateItem | world,ll,bool,commodity,quality,empire,text | Create an item on a world.

Arguments:
'll' is the location to create the item.
'bool' is true to make the item permanent. Permanent story items persist in the game after the story ends. Nonpermanent story items are removed when the story ends.
'empire' is the empire of origin of the item.
'text' is inscribed on the item if not blank. | item | | worldCreateNpc | world,ll,text,gender,hand,empire,dna,stage,bool | Creates an npc on 'world' at 'll'.

Arguments:
'text' is the name of the new npc. If an npc with the same name and story instance exists in the environment, it is moved rather than create a new npc.
'dna' specifies the DNA of the npc. However, if the avatar of the story has ever met a story npc with the same name, in any prior encounter, then the 'dna' argument is overridden by the DNA of the original npc met by the avatar.
'stage' specifies the growth stage of the npc.
'bool' specifies the visibility of the npc. | npc | | worldCreateShip | world,ll,real,sc,quality,empire,text | Create a spaceship at a world.

Arguments:
'll' is the location to create the spaceship. When altitude AGL is 0, a 50m radius about ll must be clear of obstructions to succeed.
'real' is the altitude in meters AGL if alt<500; alt>500 puts the ship at atmosphere radius + alt. Standard orbit is about 2000m above the atmosphere. Parking altitude is about 1500m above the atmosphere.
'sc' is the blueprint id of the ship.
'empire' is the empire who owns the spaceship.
'text' is the name of the ship, set randomly if blank. | ship | | worldCreateVehicle | world,ll,real,commodity,quality,empire | Create a vehicle on a world.

Arguments:
'll' is the location to create the vehicle. A 5m radius about ll must be clear of obstructions to succeed.
'real' is altitude above ground level in meters. Negative is below ground level.
'empire' is the empire who owns the vehicle. | vehicle | | worldHasCity | world | Test if the world has any cities at all. | bool | | worldHengeCeremony | world,ll,int | Sets the state of the henge ceremony, if there is a henge.

Arguments:
'int' is ceremony state: 1=Active, 0=Inactive. | void | | worldHydrographics | world | Returns the world's water percentage in the range 0 to 100. | int | | worldIndigenous | world | Test if the world has indigenous people.

Returns: 0=Impossible to have Indigenous, 1=Same as Avatar, 2=Alien to Avatar, 3=Virgin World with no Indigenous. | int | | worldIsGasGiant | world | Test if the world is a gas giant. | bool | | worldIsMoon | world | Test if the world is a moon. Moons are small globe satellites with no atmosphere. | bool | | worldIsPlanet | world | Test if the world is a planet. Planets are the primary worlds in a solar system, apart from gas giants. | bool | | worldIsPlanetoid | world | Test if the world is a planetoid. Planetoid is a tiny globe in an asteroid belt, orbiting a sun. | bool | | worldIsRing | world | Test if the world is a ring. A ring is a band of small rocks and ice, orbiting a planet. | bool | | worldIsRingworld | world | Test if the world is a ringworld arc section. | bool | | worldIsTitan | world | Test if the world is a titan. Titans are large satellites with an atmosphere. | bool | | worldLandLocation | world,real,real | Returns a location that is on land.

Arguments:
First 'real' is minimum terrain altitude MSL, in meters.
Second 'real' is minimum radius from forbidden zones, in meters; 0 does not avoid forbidden zones. | ll | | worldLandLocationAvoid | world,real,real,ll,real | Returns a location that is on land not near 'll'.

Arguments:
First 'real' is minimum terrain altitude MSL, in meters.
Second 'real' is minimum radius from forbidden zones, in meters; 0 does not avoid forbidden zones.
'll' is location to avoid.
Third 'real' is minimum distance away from avoid location, in meters. | ll | | worldLandLocationNear | world,ll,real,real,real | Returns a location that is on land somewhere near 'll'.

Arguments:
First 'real' is minimum terrain altitude MSL, in meters.
Second 'real' is minimum distance from 'll', in meters.
Third 'real' is maximum distance from 'll', in meters. | ll | | worldOrbitFrigid | world | Test if the world is in the frigid orbit zone. Also true if the world is a satellite of a world in that zone. | bool | | worldOrbitHabitable | world | Test if the world is in the habitable orbit zone. Also true if the world is a satellite of a world in that zone. | bool | | worldOrbitInferno | world | Test if the world is in the inferno orbit zone. Also true if the world is a satellite of a world in that zone. | bool | | worldOrbitInner | world | Test if the world is in the inner orbit zone. Also true if the world is a satellite of a world in that zone. | bool | | worldOrbitOuter | world | Test if the world is in the outer orbit zone. Also true if the world is a satellite of a world in that zone. | bool | | worldRelativeLL | world,ll,real,real | Returns a location that is offset from another location.

Arguments:
'll' is the reference location.
First 'real' is horizontal offset in meters. + is easterly on a globe or east on a ringworld; - is westerly.
Second 'real' is vertical offset in meters. + is north, - is south. | ll | | worldScheduleAsteroid | world,int | Schedules an asteroid to destroy the world in 'int' minutes.

Arguments:
'world' is the world that will be the target of the asteroid.
'int' is the number of minutes before impact. Must be at least 1. | void | | worldSupportsAnimals | world | Test if the world can support animal life. World could be in the inner, habitable or outer orbit zone to support animals.

All worlds that support animals also support plants. | bool | | worldSupportsPlants | world | Test if the world can support plant life. World could be in the inner, habitable or outer orbit zone to support plants.

Worlds that support plants do not necessarily support animals. | bool |