Name:
abs
Syntax:
(abs x) -> z
Argument List:
x: any number
Returns:
z: the absolute value of that number
Category:
math
Description:
Obtains the absolute value of a number
Example:
[code](abs 1) [/code]
returns 1
[code](abs -1) [/code]returns 1
Comment:
Basic math function.
Name:
add
Syntax:
(add x1 x2 ... xn) -> z
Argument List:
x1: A number to add.
x2 ... xn: Optional numbers to add.
Returns:
z: The sum of all the numbers passed in
Category:
0.99, math
Description:
Sums up the numbers passed to it and returns the result.
Example:
[code](add 1 2 3 4 5)[/code]
returns the number 15
[code](add 1) -> 1[/code]
Comment:
Basic math function.
Name:
and
Syntax:
(and exp1 exp2 ... expn) -> True/Nil
Argument List:
exp1: an expression that evaluates to Nil or non-Nil
exp2 ... expn: optional expressions that each evaluate to Nil or non-Nil.
Returns:
boolean: the result of anding all of the expressions
Category:
logical operator
Description:
Returns True if all the expressions are not Nil otherwise returns Nil.
Example:
[code](block (someCondition)
(setq someCondition True)
(and someCondition Nil)
)[/code]
This will return a Nil.
Comment:
Logical functions are very important in if and while functions.
Name:
append
Syntax:
(append a b [...]) -> concatenated list
Argument List:
a: A list, string, integer, boolean or literal you want to start the new list.
b: A list, string, integer, boolean or literal you want to append on to the previous argument.
[...]: Optional list, string, integer, boolean or literal. Can be repeated.
Returns:
list: A new list containing all the elements of the passed in arguments with their order preserved.
Category:
list
Description:
Makes a new list with all the elements of the passed in arguments in the order that they came in at.
At least two arguments must be provided.
If the first argument is not a list, an empty list with that argument as first element will be created, and the rest of the arguments will be appended to that list
Example:
[code](append '(a b c) '(d e))[/code]
Will return the list (a b c d e)
[code](append '(a) '(d) '(b e))[/code]
Will return the list (a d b e)
Comment:
It is important to note, that if one of the arguments is a list, then the *elements* of that list will be appended one by one, and *not* the list itself. As an example
(append "a" '(b c)) -> (a b c) not (a (b c))
But any list *inside* a list will be preserved. Example:
It is important to note, that if one of the arguments is a list, then the *elements* of that list will be appended one by one, and *not* the list itself. As an example
(append "a" '(b '(c d))) -> (a b (c d))
Name:
apply
Syntax:
(apply lambda list) -> return value of lambda
Argument List:
lambda: The function (lambda) you want to run.
list: A list of arguments you want the function to be run with.
Returns:
Whatever the lambda returns.
Category:
function operator
Description:
Runs the function as though it was called normally using the list as its arguments.
Example:
[code](block (someArgumentList)
(setq someArgumentList '(True True Nil))
(apply and someArgumentList)
)[/code]
This will return Nil.
[code](block (someArgumentList)
(setq someArgumentList '(1 34))
(apply add someArgumentList)
)[/code]
This will return 35.
Comment:
Much more powerful than first appears. Both the function and argument list can vary.
Name:
armGetHitPoints
Syntax:
(armGetHitPoints type) -> Hit points of armor
Argument List:
type: The type of the armor you want to get the name from. This is not the UNID.
Returns:
The amount of hit points of the armor
Category:
0.99, armortype, armor
Description:
Get the max hit points on the armor segment.
Example:
Get the player ships forward armor segment, and see how many hitpoints it has:
[code]
(armGetHitPoints (objGetArmorType gPlayerShip 0))
[/code]
Comment:
It returns the max hit points of the armor segment, and not the actual hitpoints of the segment if it is damaged. (use objGetArmorDamage instead)
Name:
armGetName
Syntax:
(armGetName type) -> Name of the armor
Argument List:
type: The type of the armor you want to get the name from. This is not the UNID.
Returns:
string: The name of the armor
Category:
name, armor, armortype
Description:
Returns the name of the type of armor you passed to it.
Example:
[code](armGetName (objGetArmorType gPlayerShip 0))[/code]This returns your forward armor.
Comment:
I don't really understand what is the point of type. Anyone have any clues on that? Item Create works with UNID but not this.
Name:
armGetRepairCost
Syntax:
(armGetRepairCost type) -> Cost to repair 1 hit point
Argument List:
type: The type of the armor you want to get the repair cost from. This is not the UNID.
Returns:
integer: The cost of repairing one point of damage of this armor.
Category:
cash, repair/damage, armor, armortype
Description:
Returns the repair cost of one point of damage for this armor type.
Example:
[code](armGetRepairCost (objGetArmorType gPlayerShip 0))[/code]This returns the cost of repairing one point of damage on your forward armor.
Comment:
More armor type fun. The only way to get this is to install it and do objGetArmorType. :P
Name:
armGetRepairTech
Syntax:
(armGetRepairTech type) -> Tech level required to repair
Argument List:
type: The type of the armor you want to get the repair tech from. This is not the UNID.
Returns:
integer: The tech level needed for a station to repair this armor.
Category:
armor, repair/damage, station, armortype
Description:
Returns the tech level needed to repair this armor type for a station.
Example:
[code](armGetRepairTech (objGetArmorType gPlayerShip 0))[/code]This returns the tech needed to repair this armor.
Comment:
This is not a real limitation it is more of a by convention no station below the tech level can repair the armor.
Name:
armIsRadiationImmune
Syntax:
(armIsRadiationImmune type) -> True/Nil
Argument List:
type: The type of the armor you want to get if the armor is radiation immune from. This is not the UNID.
Returns:
boolean: True if the armor is radiation immune ,otherwise returns Nil.
Category:
armor, radiation, armortype
Description:
Checks to see if the armor is radiation immune and returns the result.
Example:
[code](armIsRadiationImmune (objGetArmorType gPlayerShip 0))[/code]Returns True if the armor type of the forward armor is radiation immune false otherwise.
Comment:
Yay no more ArmorType after this.
Name:
block
Syntax:
(block list exp1 ... expn) -> value of last expression
Argument List:
list: A list of local variables. Can be Nil or empty. Can contain initial values.
exp1 ... expn: A series of expressions (anything you want to do).
Returns:
Whatever the last expression in the block returns
Category:
control structure
Description:
Allows you to run several expressions one right after the other. Also used to wrap variables that you want to be local. Those variables can be given default values using the syntax (variable value). See example for more details
Example:
[code]
(block Nil
(block (A)
(setq A "value")
(block ((B "default") C)
; A, B, and C are valid here.
(dbgOutput A) ; prints "value"
(dbgOutput B) ; prints "default"
(dbgOutput C) ; prints "Nil"
; Setting a variable not declared
; in any parent's list makes a global:
(setq D "global")
)
; A is still valid here.
; B and C are invalid,
; and would cause errors.
(dbgOutput D) ; prints "global"
)
)
[/code]
Comment:
This is a very important function because often you want to run things one right after another. It is one of the most if not the most common function in the xml.
Name:
cat
Syntax:
(cat s1 s2 ... sn) -> string
Argument List:
s1: A string, integer, boolean or literal that you want to concatenate with others
s2 ... sn: Optional strings, integers, booleans or literals, each to be contcatenated.
Returns:
string: A string composed of all the arguments concatenated together in the order of the argument list.
Category:
string operator
Description:
Sticks together strings, integers, booleans or literals forming larger strings in the order you supply with the argument list.
Example:
[code](cat "He" "l" "llo W" "orld" 1 "!!" 1)[/code]This returns the string "Hello World1!!1".
Comment:
A very useful function for making your output look nice.
Name:
cnvDrawImage
Syntax:
(cnvDrawImage x y imageDesc [screen] [ID])
Argument List:
x: the x coordinate of image to be drawn
y: the y coordinate of image to be drawn
imageDesc: a list of 5 numbers. they are:
the first is the UNID of the image resource as a number,
the second and the third are the x,y coordinates in pixels of the resource image
(from the top left corner of the image)
the fourth and fifth are the sizes of the resource image in pixels.
(first width then height)
[screen]: unsure
[ID]: unsure
Returns:
boolean: true if successful
Category:
canvas, screen
Description:
Lets you draw images onto canvas screens
Example:
from &dsNeurohackHelp;
(cnvDrawImage 120 0 (list &rsNeurohackControls; 0 0 70 70))
As you can see, [Screen] nor [ID] is used.
Comment:
The coordinates 0,0 correspond to the top left of the dockscreen. You have about 600x400 pixels to draw on.
As you can see, [Screen] and [ID] are not used.
More on that here: http://www.neurohack.com/transcendence/forums/viewtopic.php?p=24021#p24021
Name:
cnvDrawRect
Syntax:
(cnvDrawRect x y width height color [screen] [ID])
Argument List:
x: the x coordinate of image to be drawn
y: the y coordinate of image to be drawn
width: width of the rectangle
height: height of the rectangle
color: a list of 3 numbers in hexadecimal to define color
[screen]: unsure. Guess: the screen you want to draw on
[ID]: unsure
Returns:
boolean: true if successful
Category:
screen, canvas
Description:
Lets you draw a rectangle of specified size and color on a canvas screen.
Example:
From &dsNeurohack;
(cnvDrawRect 0 60 528 80 '(74 71 95))
As you can see, [Screen] and [ID] are not used.
Comment:
The coordinates 0,0 correspond to the top left of the dockscreen. You have about 600x400 pixels to draw on.
As you can see, [Screen] and [ID] are not used.
More on that here: http://www.neurohack.com/transcendence/forums/viewtopic.php?p=24021#p24021
Name:
cnvDrawText
Syntax:
(cnvDrawText x y text font color alignment [screen] [ID])
Argument List:
x: the x coordinate of text to be drawn
y: the y coordinate of text to be drawn
text: text you want to be drawn
font: font to draw the text in
color: a list of 3 numbers (each from 0 to 255) to define color
alignment: the point from which the text will be drawn ('center, 'left or 'right')
[screen]: unsure
[ID]: unsure
Returns:
boolean: true if successful
Category:
screen, canvas
Description:
Lets you draw text to a canvas dockscreen
Example:
(cnvDrawText 264 80 "Neurohack Successful!" 'SubTitleBold '(54 176 72) 'center).
As you can see, [Screen] and [ID] are not used.
Comment:
The coordinates 0,0 correspond to the top left of the dockscreen. You have about 600x400 pixels to draw on.
A list of font sizes are here:
http://wiki.neurohack.com/transcendence/wiki/functions/legend#font_sizes
As you can see, [Screen] and [ID] are not used.
That is explained here: http://www.neurohack.com/transcendence/forums/viewtopic.php?p=24021#p24021
Name:
dbgLog
Syntax:
(dbgLog expression^1)
Argument List:
expression: Prints out the expression to the log.
Returns:
A string representing what was output to the log file.
Category:
debug, 0.99
Description:
Outputs the expressions to the debug.log file. Can be lists, strings, functions (only outputs the name of the function), or numbers.
Example:
[code](dbgLog '(1 2 3 4))[/code]
Outputs (1 2 3 4) to the log file.
Comment:
Very useful in outputting large amounts of data or data that you want to look over at your leisure.
Name:
dbgOutput
Syntax:
(dbgOutput s1 [s2 ... sn])
Argument List:
string: The stuff you want outputted to the debug console. If the argument is not a string it will be converted into a string.
[s2 ... sn]: More strings to be outputted. They will be concatenated onto the previous strings
Returns:
condition: True if it successfully outputted the string
Category:
debug
Description:
Outputs the string onto the debug console.
Example:
[code](dbgOutput "if you can see this you have the debug console open")[/code]
Outputs to the debug console
if you can see this you have the debug console open
True
Comment:
Very useful in testing scripts and seeing where things go wrong.
Does not handle \n but does handle \".
Name:
divide
Syntax:
(divide x y) -> z
Argument List:
x: The dividend of the two numbers.
y: The divisor of the two numbers.
Returns:
z: The result of the two numbers divided with everything after the decimal point dropped.
Category:
math
Description:
Returns the result of the two numbers divided and dropping everything after the decimal point.
Example:
[code](divide 5 3)[/code]
This will return a 1.
[code](divide 5 2)[/code]
This will return a 2.
[code](divide 5 (add 1 1))[/code]
This will also return a 2.
Comment:
Basic math function. If you hear the term integer division this is what that is referring too.
Name:
ecoExchange
Syntax:
(ecoExchange amount fromCurrency toCurrency) -> amount
Argument List:
amount: number to be exchanged
fromCurrency: current currency
toCurrency: new currency
Returns:
amount: the amount of new currency
Category:
1.06, economy
Description:
With the addition of 1.06 economytypes, this function allows one to exchange credits to rin and etc.
Example:
(ecoExchange 100 &ecCreditEconomy; &ecRinEconomy;)
This exchanges 100 credits to 20 rins.
In this case, the return is 20.
Comment:
Basic economy function. First introduced in 1.06.
Name:
enum
Syntax:
(enum list itemVar exp) -> value of last expression
Argument List:
list: A list of elements you want to walk through.
itemVar: Name of variable that will be used to hold the current element you are at in the enum. Does not need to be defined beforehand.
exp: The expression you want to evaluate for each element in the list. The element will be available inside the expression under the name you used in `itemVar'.
Returns:
Whatever the last function run in this returns.
Category:
iteration, list
Description:
A function allowing you to run an expression using the variable to store the element you are at for every element in a list.
Example:
[code](enum '(a b c d) theElement
(dbgOutput theElement)
)[/code]
Will display on the debug console.
[code]a
b
c
d
True[/code]
Comment:
Very useful function because you often want to do the same thing to everything in a list.
Name:
enumWhile
Syntax:
(enumWhile list condition itemVar exp) -> value of last expression
Argument List:
list: A list of elements you want to walk through.
condition: Stops enum if condition is Nil.
itemVar: Name of the variable that will be used to hold the current element you are at in the enum. Does not need to be defined beforehand.
exp: The expression you want to evaluate for each element in the list. The element will be available inside the expression under the name you used in `itemVar'.
Returns:
Whatever the last expression evaluated inside returns.
Category:
list, iteration
Description:
A function allowing you to evaluate an expression using the variable to store the element you are at for every element in a list unless condition is Nil.
Example:
[code](block (condition)
(setq condition True)
(enumwhile '(a b c d) condition theElement
(block Nil
(if (eq theElement 'b) (setq condition Nil))
(dbgOutput theElement)
)
)
)[/code]
This will display on the debug console.
a
b
True
Comment:
Basically a enum with an if inside of it.
Name:
envHasAttribute
Syntax:
(envHasAttribute number string)
Argument List:
number: The unid of the space environment you are querying about.
string: The name of the attribute.
Returns:
True if it has it nil otherwise.
Category:
condition query, 0.99, unid
Description:
Checks to see if the given space environment has the given attribute and returns the result.
Example:
(envHasAttribute &seNebula; 'nebula)
Will return true.
Comment:
Useful in checking if a certain type of environment is near a space object.
Name:
eq
Syntax:
(eq exp1 [exp2 ... expn]) -> True/Nil
Argument List:
exp1: An expression you want to check for equality to other expressions. It will be evaluated, and it's value used for the comparison
[exp2 ... expn]: More expressions to compare.
Returns:
boolean: True if they are all equal. Nil otherwise.
Category:
logical operator
Description:
Compares any amount of expressions and returns True if they are all equal, Nil if they are not.
Example:
[code](eq '(a b) '(a b))[/code]
This will return True.
[code](eq 2 (add 1 1))[/code]
This will return True.
Comment:
Not as useful as first appears. If you want to compare two objects by just certain properties you need to create a custom function.
Name:
errBlock
Syntax:
(errBlock list exp1 ... expn expError)
Argument List:
list: A list of temporary variables. The first variable stores any error that happens
exp1 ... expn: The expressions you want to run.
expError: The expression you want to run if an error occurs.
Returns:
The result of the last expression
Category:
control structure, error
Description:
Allows you to run expressios one right after the other. If there is an error the error is stored in the error variable and then runs the last function. If no errors the last function isn't run.
Example:
[code](errblock (errVar)
(dbgOutput "Running normally")
(divide 10 0)
(dbgOutput "Not running normally")
(dbgOutput "The error is " errVar)
)[/code]Displays
Running normally
The error is Division by zero (10 0) ### (divide 10 0) ###
True
Comment:
Like iserror not as useful as it could be due to many errors hard crash the game and you can't throw your own errors.
Name:
error
Syntax:
(error mesage) -> error
Argument List:
message: The message you want to display as your error
Returns:
error: the raised error
Category:
error
Description:
Raise an error. For use with isError and errBlock
Example:
(error "Something went wrong")
Raises an error (presumably because something went wrong... you should probably be more specific)
Comment:
Discussed in ticket #326
Name:
eval
Syntax:
(eval expr) -> value of evaluated expression
Argument List:
expression: The thing you want to evaluate. It can handle numbers, function, strings, and lists. What it does, depends on what argument it gets.
Returns:
If it is passed a number or lamdba function it just returns that otherwise tries to run the list as a function and returns what that function returns, or if it is a string it returns the value of the variable with that name.
Category:
function operator, variable, string operator
Description:
Returns the evaluated expression. If it is passed a number or function it just returns that if it is a list tries to run the list as a function and return what it returns, or if it is a string it returns the value of the variable with that name.
Example:
[code](eval '(add 1 1))[/code]
This is a list case. This will return the number 2.
[code](block (varies)
(setq varies "I am a variable")
(eval "varies")
)[/code]
This is a string case. This will return the string "I am a variable".
[code](eval (add 1 1))[/code]
Even though it is similar to the list case this is a number case (the (add 1 1) is run first). This will return the number 2.
[code](eval add)[/code]
This is the function case. This will return the function add.
[code](block (theString)
(setq theString "(add 3 5)")
(eval (link theString))
)[/code]
Maybe the most intersting use of (eval ...) is in combination with (link ...), which converts a string into an expression tree.
The above example will return the integer "8".
Comment:
Some very interesting things can be done with this. The string case is the most interesting due to the list case can be emulated with apply and the other two cases being trivial.
Name:
filter
Syntax:
(filter list variable function) => (list)
Argument List:
list: The list that will be filtered.
variable: The name of the variable to be used in the function.
function: A boolean function that is used to filter the list.
Returns:
list: A list where all elements belong to the passed in list and return true for the boolean function.
Category:
0.99, list
Description:
Filter takes the passed in list and returns a new list made up of elements of the passed in list that returned true for the boolean function.
Example:
[code](filter '(1 2 3 5 7 9 11 13) element (gr element 5))[/code]
That code will return the list (7 9 11 13)
Comment:
Very nice helper function that allows you to filter out stuff you do not want in lists.
Name:
find
Syntax:
(find source target [keyIndex]) -> position of target in source (0-based)
Argument List:
source: The string or list that you are looking for the other expression in.
target: The expression you are looking for.
[keyindex]: The index in the source you want to start looking at
Returns:
integer: 0 based index of the expression you where looking for. Returns nil if not found.
Category:
list, string operator, 0.99
Description:
Finds the index of the first time that the second argument appears in the first argument and returns it.
Example:
[code](find '(1 2 3 4 5) 3)[/code]
Returns 2
Comment:
Nice little function helpful in formatted strings and lists.
Name:
fmtCurrency
Syntax:
(fmtCurrency currency [amount]) -> string
Argument List:
currency: UNID of the currency you want to format the string in
[amount]: the amount you want in the string
Returns:
string: the name of the currency plus an amount, if specified.
Category:
economy, 1.06
Description:
Allows the formatting of currency in text.
Example:
(fmtCurrency &ecRineconomy; 5000)
returns 5000 rin.
Comment:
You may use fmtCurrency to format a string containing a currency value.
Name:
fncHelp
Syntax:
(fncHelp expression) -> help string
Argument List:
expression: the expression you want to get the help text for
Returns:
a help string that describes how to use the expression
Category:
function, debug
Description:
This function is used to get the built in help string for functions. It only works on primitives (built in functions).
Example:
Comment:
(fncHelp fncHelp) -> (fncHelp ...)
Yay for self referential examples :P
Name:
for
Syntax:
(for var from to exp) -> value of last expression
Argument List:
var: The storage for the counter. This will increase by one at the end of the function every time it is run.
from: The number that will be the initial value
to: The last number that the variable will be run as.
expr: The expression that will be evaluated with the current value set available under the name set in `variable'
Returns:
Whatever the last expression returns.
Category:
iteration
Description:
Evaluates expression using variable for every value between and including the two numbers.
Example:
[code](block (sum)
(setq sum 0)
(for varies 3 8 (setq sum (add varies sum)))
)[/code]
This returns the number 33.
Comment:
Useful in many ways. From doing a function on only a certain section of a list to calculating math problems.
Name:
gamSetCrawlImage
Syntax:
(gamSetCrawlImage imageUNID) -> True/Nil
Argument List:
imageUNID: the UNID of the image that needs to be drawn in the prologue.
Returns:
Boolean: true or Nil depending upon success
Category:
prologue
Description:
Allows the drawing of an image in the prologue (the image and text that appearss once you start a new game)
Example:
From &adPart1Desc;
(gamSetCrawlImage &rsProlog1;)
Comment:
Name:
gamSetCrawlText
Syntax:
(gamSetCrawlText text) -> True/Nil
Argument List:
text: text that is displayed in front of the prologue image.
Returns:
Boolean: true/nil depending upon success
Category:
prologue
Description:
Sets the text that will be displayed in the prologue (the screen that appears when you start a new game)
Example:
from &adPart1Desc;
(gamSetCrawlText (cat
"When the dream came, you knew Domina had chosen you. "
"You would sacrifice everything for the chance She offered: "
"to join Her at the Galactic Core, the eternal temple of the gods.\n\n"
"Leaving your former life behind, you begin the long journey. "
"No matter what obstacles lie in your path "
"you will not fail Domina. You will reach the Galactic Core."
))
Comment:
The Network uses this very effectively.
Name:
geq
Syntax:
(geq a [b ... bn]) -> True if a >= b >= bn
Argument List:
a: The first expression you want to compare.
[b ... bn]: The next expressions you want to compare.
Returns:
boolean: The expressions are compared left to right. If there is any case where the left value is "less" then the right value, `geq' will return Nil. Else it returns True.
Category:
logical operator
Description:
A comparison function that returns true if the left hand side is greated than or equal to the right hand side. The same as >= in math.
Integers are compared by value, so (geq 1 1) -> True, but (geq 1 2) -> Nil
Strings are compared by alphabetical position, so (geq "a" "A") -> True, but (geq "a" "B") -> Nil
Lists are compared by length, so (geq '(1) '(2)) -> True, but (geq '(2) '(1 1)) -> Nil
It is advised to play around with this a bit to get a feeling of how things compare
Example:
[code](geq 7 3)[/code]
Returns True.
[code](geq "Betel" "Betelgeuse")[/code]
Returns Nil.
[code](geq '(a a b) '(c d e))[/code]
Returns Nil.
[code](geq "B" "b")[/code]
Returns True.
Comment:
I am not sure how lists are compared but other than that this is your standard comparison function.
Name:
gr
Syntax:
(gr a [b ... bn]) -> True if a > b > bn
Argument List:
a: The first expression you want to compare.
[b ... bn]: The next expressions you want to compare.
Returns:
boolean: The expressions are compared left to right. If there is any case where the left value is less or equal to the right value, `gr' will return Nil. Else it returns True.
Category:
logical operator
Description:
A comparison function that returns true if the left hand side is greated than the right hand side. The same as > in math.
Integers are compared by value, so (gr 2 1) -> True, but (gr 1 1) -> Nil
Strings are compared by alphabetical position, so (gr "b" "A") -> True, but (gr "b" "B") -> Nil
Lists are compared by length, so (gr '(2 2) '(2)) -> True, but (gr '(2) '(1 1)) -> Nil
It is advised to play around with this a bit to get a feeling of how things compare
Example:
[code](gr 7 3)[/code]
Returns True.
[code](gr "Betel" "Betelgeuse")[/code]
Returns Nil.
[code](gr '(a a b) '(c d e))[/code]
Returns Nil.
[code](gr "B" "b")[/code]
Returns Nil.
Comment:
Name:
if
Syntax:
(if condition exp1 [exp2]) -> value of invoked expression
Argument List:
condition: anything that evaluates to Nil or non-Nil
exp1: an expression that gets invoked if 'condition' evaluates to non-Nil (if it is 'true')
[exp2]: an optional expression that gets invoked if 'condition' evaluates to Nil (i.e. is 'false')
Returns:
Whatever the expression that gets invoked returns
Category:
control structure
Description:
Basic branching function. Allows executing something only if a certain condition is met. A fundamental thing.
Example:
[code](if (eq (sysGetNode) "SE")
(objSendMessage gPlayerShip Nil "We are still in Eridani system")
(objSendMessage gPlayerShip Nil "We are on the journey to the core")
)
[/code]
Comment:
It's hard to imagine a script of more than several functions which wouldn't contain some sort of branching, either with 'if' or 'switch' functions.
Name:
int
Syntax:
(int string)
Argument List:
string: a string you want returned as number
Returns:
number: the integer version of the string
Category:
0.99, string operator
Description:
Takes a string representation of a number and returns it as an actual number. I can also convert hexadecimal strings.
Example:
[code](int "2")[/code]
Returns 2
[code](int 2)[/code]
Returns 2
[code](int "two")[/code]
Returns 0
[code](int "0xDCBA")[/code]
Returns 56506
Comment:
Very useful function for converting a string to an integer. Eg. after storing a integer on a space object, it will be returned as a string. Use this function to convert it back to a number. Can also convert hexadecimal strings to integers.
Name:
isAtom
Syntax:
(isAtom expr) -> True/Nil
Argument List:
expr: The expression you want to test for being an atom.
Returns:
boolean: True if the expression is an atom, Nil otherwise.
Category:
atom, condition query
Description:
Returns True if the expression is an atom. An atom is anything that can not be split up (*hrhhmm*), so it includes everything that is not a list.
Example:
[code](isAtom "Betel")[/code]
Returns true.
[code](isAtom isAtom)[/code]
Returns true.
[code](isAtom '(a))[/code]
Returns Nil.
Comment:
Useful in error checking.
Name:
iserror
Syntax:
(iserror expression)
Argument List:
expression: The expression that you want run and see if it is an error.
Returns:
conditional: True if it does contain an error, Nil otherwise.
Category:
error
Description:
Returns if the expression evaluated to an error or not.
Example:
[code](iserror (divide 10 0))[/code]
Returns True.
Comment:
Not as useful as would first seem due to many errors giving you a hard crash and the fact you can't raise your own errors.
Name:
isfunction
Syntax:
(isfunction expr) -> True/Nil
Argument List:
expr: The expression you want to test for being a function (lambda or builtin).
Returns:
boolean: True if the expression is a function (lambda or builtin). Nil otherwise.
Category:
condition query, function operator
Description:
Checks if something is a function or not and returns True if it is.
Example:
[code](isfunction "Betel")[/code]
Returns Nil
[code](isfunction isfunction)[/code]
Returns True
Comment:
Useful in error checking.
Name:
isInt
Syntax:
(isInt expr) -> True/Nil
Argument List:
expr: The expression you want to test for being an integer.
Returns:
boolean: True if expression is an integer. Nil otherwise.
Category:
condition query
Description:
Checks to see if the expression is an integer and if it is returns True. Otherwise returns Nil.
Example:
[code](isInt "Betel")[/code]
Returns Nil.
[code](isInt 45)[/code]
Returns True.
Comment:
Useful in error checking like all the condition query functions.
Name:
isPrimitive
Syntax:
(isPrimitive expression) -> boolean
Argument List:
expression: the expression you want to test
Returns:
boolean: whether the expression is a primitive or not
Category:
function
Description:
This function checks if the given expression is a built in function (a "primitive") or a lambda. It is mostly used in debugging and exploration of tscript.
Example:
[code]
(isPrimitive objSetData) -> True
(isPrimitive (lambda nil ...)) -> Nil
[/code]
Examples of a true and a false use. Note that the lambda in the second example is not completely correct
Comment:
Name:
item
Syntax:
(item list index) -> list item or Nil
Argument List:
list: the list you want to get an element from.
index: the integer position of the element you want to get.
Returns:
If index is less than zero, return first element. If the index is greater or equal than the length of the list, return Nil. Otherwise return the element at given index in the list.
Category:
list
Description:
A function to return an element from a list.
IMPORTANT: *The list count starts from 0, so, the index of the first element is 0*
Example:
[code](item '(a (b e) (c d) d) 2)[/code]
Returns (c d).
[code](item '(a b c d) 0)[/code]
Returns a.
[code](item '(a b c d) -1)[/code]
Returns a.
[code](item '(a b c d) 4)[/code]
Returns Nil.
Comment:
Very important list function.
DEPRECIATED - Alias of @
Name:
itmAtCursor_deprecated
Syntax:
(itmAtCursor_deprecated itemListCursor)
Argument List:
itemListCursor: A pointer to the item that you want the itemStruct of. (can someone think of something better to say than pointer.
Returns:
An itemStruct of the item pointed at by the itemListCursor.
Category:
0.98, item, deprecated
Description:
Gets the itemStruct of the item being pointed at by the itemListCursor.
Example:
[code](objEnumItems gPlayerShip "sI" itemCursor
(itmGetName (itmAtCursor itemCursor) 0)
)[/code]
This returns the name of the name of the shield that is equipped by the player.
Comment:
objEnumItems or scrGetItemListCursor is the only way to get the itemListCursor. This limits what you can do with functions that use the itemListCursor greatly.
Most functions can work with itemStructs so you don't have to worry about it much except doing this function in nearly every objEnumItems or scrGetItemListCursor.
Function deprecated in 0.99
Name:
itmCreate
Syntax:
(itmCreate itemUNID count) -> item
Argument List:
itemUNID: The UNID of the item you want to create.
count: The amount of items you want to create.
Returns:
An itemStruct of the items you created.
Category:
unid, item, create
Description:
Creates `count' amount of items with the given `itemUNID' and returns a itemStruct representing all the items created.
Example:
[code](itmGetName (itmCreate 0x4001 1) 0)[/code]
Returns the string segment of light titanium armor.
Comment:
Very useful function allowing the creation of any item you feel like in code.
Name:
itmCreateByName
Syntax:
(itmCreateByName criteria name [count]) -> item
Argument List:
criteria: the criteria that the item must meet.
name: the name or part of the name of the item to create.
[count]: the optional number of items you want to create. If not given, one item will be created.
Returns:
An itemStruct of an item that meets the criteria and has `name' as part of its name.
Category:
random, item, create
Description:
Makes a itemStruct of an item that meets the criteria and has `name' as part of its name with number of them. If more than one item meets the conditions it will pick one at random.
Example:
[code](itmGetName (itmCreateByName "s" "generator" 1))[/code]
Returns one of the following at random Cydonian shield generator, Cydonian heavy shield generator, Kaidun shield generator, Solon shield generator, Nephren P25 shield generator, superconducting shield generator, Yoroi S100 shield generator, Yoroi S500 shield generator, Nephren B700 shield generator, Trenton field generator, Yoroi MX shield generator, plasma shield generator, Nephren X1 shield generator, or Lazarus shield generator.
Comment:
Used in the trading station.
Name:
itmCreateRandom
Syntax:
(itmCreateRandom criteria levelDistribution) -> item
Argument List:
criteria: A string representing the criteria of the item you want to create.
levelDistribution: A formated string specifying what rarity of items will appear at what level.
Returns:
A itemStruct representing the randomly picked item.
Category:
random, create, item
Description:
Creates a random item matching the criteria and the string. For a more details description of the levelDistribtion string, see
http://wiki.neurohack.com/transcendence/wiki/functionlegend#level_distribution
Example:
[code](itmGetName (itmCreateRandom "s" "----- --c--"))[/code]
Returns the name of a random shield of level 8.
Comment:
Useful for creating a item at random.
Please note that the frequency in the string is the frequency of the appearing level and not the frequency of the items.
Moreover itmCreateRandom doesn't pick up items with frequency "notrandom"
Name:
itmEnumTypes
Syntax:
(itmEnumTypes criteria itemVar exp) -> value of last expression
Argument List:
criteria: The criteria an item must meet to be enumerated.
itemVar: The name of a variable that will contain each item that we are enumerating. Does not need to be defined beforehand.
exp: The expression you want to evaluate for every item that meets the criteria. It will have the item available as a UNID under the name used in `itemVar'
Returns:
Whatever the last function run in it returns.
Category:
iteration, item
Description:
For each item that meets the criteria in the game, evaluate the expression with the item's itemstruct in the itemVar.
Example:
[code](itmEnumTypes "s" itemType
(dbgOutput (itmGetName itemType))
)[/code]
This will display the name of every shield in the game.
Comment:
Useful if you want to go through all the items of a kind, like in identifying them.
Name:
itmGetActualPrice
Syntax:
(itmGetActualPrice item) -> actual price of a single item
Argument List:
item: The item from what you want to get the real price from. Must be an itemStruct, not a UNID
Returns:
integer: The actual price of the object. It ignores the unknown price (like barrels before you use them all cost the same, this would see past that)
Category:
item, cash
Description:
Returns the price of the object as if it is a known item.
Example:
[code](itmGetActualPrice (itmCreate 0x4001))[/code]
This will return 20. Ok I know this isn't a helpful example but you can't use this function well in a simple example.
Comment:
Look at the Trading Post script for a real use of this code.
Name:
itmGetArmorInstalledLocation
Syntax:
(itmGetArmorInstalledLocation item) -> segment #
Argument List:
item: The item of armor you want to know the location of. Must be an itemStruct not a UNID
Returns:
-1 one if not installed, otherwise returns the segment number of where it is installed.
Category:
armor, item
Description:
Returns the location of the armor.
Example:
[code](itmGetArmorInstalledLocation (scrGetItem gScreen))[/code]
Returns the location of the currently selected armor.
Comment:
Useful in working with armors. Such as repairing and enhancing armors.
Name:
itmGetArmorType
Syntax:
(itmGetArmorType item) -> type
Argument List:
item: the item you want to get the armor type of. The item has to be an armor of course.
Returns:
type: the type of armor
Category:
armor, item, armortype
Description:
Armors in transcendence have their own set of functions. When you want to use these, you need the type of the armor, not the itemstruct.
Example:
Comment:
Name:
itmGetAverageAppearing
Syntax:
(itmGetAverageAppearing item) -> number
Argument List:
item: The item in question.
Returns:
number: average number that appear randomly
Category:
item
Description:
Allows one to see the average amount of an item appearing randomly.
Example:
taken from &dsExchangeSell;
[code]
(block (thisitem)
(setq thisItem (scrGetItem gScreen))
(itmGetAverageAppearing thisItem)
)
[/code] Is used to determine if a station has too much of an item.
Comment:
Used once in Transcendence.tdb
Name:
itmGetCategory
Syntax:
(itmGetCategory item) -> item category
Argument List:
item: The item you want to know the category of.
Returns:
An integer representing what category the item belongs to. See description for categories.
Category:
item
Description:
The item can be any of the categories found on this page on the wiki:
http://wiki.neurohack.com/transcendence/wiki/functionlegend#categories
Example:
[code](itmGetCategory (itmCreate 0x4001 1))[/code]
Returns a 2.
Comment:
I have been using the hex numbers for itmCreate because if you want to use the debug console you have to use the numbers as it doesn't save the names in game.
Name:
itmGetCharges
Syntax:
(itmGetCharges item) -> charges
Argument List:
item: The itemStruct of the item you want to get the charges from.
Returns:
The number of charges.
Category:
item, 0.99
Description:
Returns the number of charges.
Example:
Getting the amount of charges on a Blue Credit Chip. This amount is used to determine how many credits the chip pays out.
[code]
(dbgOutput (itmGetCharges (itmCreate &itCashCardBlue; 1)))[/code]
Returns a number between 4 and 100
For setting this value see itmSetCharges
Comment:
Useful in storing a number on an item. Look at the cash roms for an example of use.
Name:
itmGetCount
Syntax:
(itmGetCount item) -> count
Argument List:
item: The itemStruct of the item you want to get the number of items from.
Returns:
The number of items.
Category:
item
Description:
Returns the number of items. An itemsStruct can contain many items, represented as a stack. This function is used for getting the number of items in that stack
Example:
[code](itmGetCount (itmCreate 0x4001 3))[/code]
Returns the number 3.
Comment:
Basic get function for items.
Name:
itmGetDamageType
Syntax:
(itmGetDamageType item) -> damage type
Argument List:
item: The itemStruct of the item you want to get the damage type of.
Returns:
The number of the items damage type if it is a weapon. Nil otherwise.
Category:
repair/damage, item
Description:
Returns the items damage type as a number. See here for a list of damage types
http://wiki.neurohack.com/transcendence/wiki/functionlegend#damage_types
Example:
[code](itmGetDamageType (itmCreate 0x400f 3))[/code]
Returns the number 2.
Comment:
Basic get function for items.
Name:
itmGetData
Syntax:
(itmGetData itemStruct string)
Argument List:
itemStruct: The item you want to get the data from.
string: The name of the data.
Returns:
The data named by the string from the item. Returns Nil if there is no data as named by the string.
Category:
0.99, data, item
Description:
Returns the data named by the string for the item.
Example:
Comment:
Could be extremely useful but the current itmSetData function is tricky to use.
Name:
itmGetDefaultCurrency
Syntax:
(itmGetDefaultCurrency item) -> currency
Argument List:
item: itemStruct of the item you want to get the default currency of
Returns:
currency: unid of the items default currency
Category:
economy, item, 1.06
Description:
used to get the default currency of an item
Example:
[code]
(setq itm (itmCreate &itLaserCannon; 1))
(itmGetDefaultCurrency itm)
[/code]
The above use of the function returns 4119, which in hexadecimal is 1017, which in turn is the UNID of the credit economy.
Comment:
Name:
itmGetFrequency
Syntax:
(itmGetFrequency item) -> frequency
Argument List:
item: The itemStruct of the item you want to get the frequency of.
Returns:
An integer representing the frequency.
Category:
item
Description:
Returns the frequency of the item as an integer. For more on frequencies, see:
http://wiki.neurohack.com/transcendence/wiki/functionlegend#frequency
Example:
[code](itmGetFrequency (itmCreate 0x4001 1))[/code]
Returns the number 20.
Comment:
Basic get function for items.
Name:
itmGetGlobalData
Syntax:
(itmGetGlobalData itemStruct string)
Argument List:
itemStruct : The item struct of the item that you want the data from.
string: The name of the data you want.
Returns:
The data named by the string from the item struct type. All space objects in the same class share the same global data. Returns Nil if there is no data as named by the string.
Category:
item, data, 0.99
Description:
Returns the data named by the string for the item struct type.
Example:
Comment:
Very helpful function for getting what data is stored in items.
Name:
itmGetImageDesc
Syntax:
(itmGetImageDesc item) -> imageDesc
Argument List:
item: the itemStruct of the item in question.
Returns:
a list of 5 numbers that comprise an imageDesc.
the first is the UNID of the image resource as a number,
the second and the third are the x,y coordinates in pixels of the resource image (from the top left corner of the image)
the fourth and fifth are the sizes of the resource image in pixels. (first width then height)
Category:
item
Description:
Allows one to get an imageDesc of an item
Example:
[code]
(itmGetImageDesc (itmCreate &itHelium3FuelRod; 1))
[/code]
returns (61725 288 96 96 96)
Comment:
Not used in Transcendence.tdb
Name:
itmGetInstallCost
Syntax:
(itmGetInstallCost item) -> cost
Argument List:
item: The itemStruct of the item you want to get the install cost of.
Returns:
The cost to install the item.
Category:
item, cash
Description:
Returns the cost to install the item.
Example:
[code](itmGetInstallCost (itmCreate 0x4001 3))[/code]
Returns the number 25.
Comment:
Basic get function for items.
Name:
itmGetInstallPos
Syntax:
(itmGetInstallPos item) -> installPos
Argument List:
item: the itemStruct of the item you want to get the installed position of
Returns:
number: a number that indicates the installed position
Category:
1.06, item
Description:
Used in conjunction with objSetDevicePos to get the position on the ship the item has been installed on
Example:
Comment:
If a device has been placed at a certain position on the ship (using objSetDevicePos, which can only be used in the items OnInstall event), this function can be used to get that position after the fact
Name:
itmGetLevel
Syntax:
(itmGetLevel item) -> level
Argument List:
item: The itemStruct of the item you want to get the level of.
Returns:
The level of the item.
Category:
item
Description:
Returns the level of the item.
Example:
[code](itmGetLevel (itmCreate 0x4001 3))[/code]
Returns the number 1.
Comment:
Basic get function for items.
Name:
itmGetMass
Syntax:
(itmGetMass item) -> mass of single item in Kg
Argument List:
item: The itemStruct of the item you want to get the mass of.
Returns:
The mass of the item in Kg.
Category:
item
Description:
Returns the mass of the item.
Example:
[code](itmGetMass (itmCreate 0x4001 3))[/code]
Returns the number 750.
Comment:
Basic get function for items.
Name:
itmGetMaxAppearing
Syntax:
(itmGetMaxAppearing item) -> max number that appear randomly
Argument List:
item: The itemStruct of the item you want to get the max number of appearing.
Returns:
The max number that will appear randomly.
Category:
item
Description:
Returns the max that will appear per random selection of the item.
Example:
[code](itmGetMaxAppearing (itmCreate 0x4001 1))[/code]
Returns the number 4.
Comment:
It is just the max value of the numberAppearing attribute.
Name:
itmGetName
Syntax:
(itmGetName item flags) -> name
Argument List:
item: The itemStruct of the item you want to get the name of.
flags: The flags to determine what form of the name is to be used.
Returns:
The name of the item.
Category:
item, name
Description:
Returns the name of the item. You must provide a flag to indicate how you want the name formatted. For more on flags, see:http://transcendence.kronosaur.com/wiki/modding/function/legend#name_flags
Example:
[code](itmGetName (itmCreate 0x4001 3) 4)[/code]
Returns the string "a segment of light titanium armor".
Comment:
Name:
itmGetPrice
Syntax:
(itmGetPrice item) -> price of a single item
Argument List:
item: The itemStruct of the item you want to get the value of.
Returns:
If unknown returns the value of the unknown type otherwise returns the value of the item.
Category:
item, cash
Description:
Returns the value of the item.
Example:
[code](itmGetPrice (itmCreate 0x4001 3))[/code]
Returns the number 20.
Comment:
This differs from itmGetAcualPrice if the item is unknown.
Name:
itmGetStaticData
Syntax:
(itmGetStaticData itemStruct string)
Argument List:
itemStruct: The item struct of the type you want to get the static data from.
string: The name of the static data.
Returns:
data: The data from the xml named by the string from the item structs type.
Category:
0.99, data, item
Description:
Returns the data from the xml named by the string from whatever the item structs type is.
Example:
Comment:
Very useful function due to you can store things in the xml before hand and get them in code.
Name:
itmGetType
Syntax:
(itmGetType item) -> UNID
Argument List:
item: itemStruct of target item
Returns:
UNID: number representing item's ItemType
Category:
item, unid, 1.04
Description:
Returns the UNID of the item
Example:
[code](eq (itmGetType (itmCreate &itHelium3FuelRod; 1)) &itHelium3FuelRod)[/code]
Returns True
Comment:
Gives fundamental data about items. Required to use (typ...) functions on items.
Name:
itmGetTypeData_deprecated
Syntax:
(itmGetTypeData_deprecated itemStruct)
Argument List:
itemStruct: The itemStruct of the item you want to get the data from.
Returns:
The data of the item.
Category:
data, deprecated, item
Description:
Returns the data of the item.
DEPRECATED: Use itmGetStaticData instead
Example:
[code](itmGetTypeData (itmCreate 0x403E 1))[/code]
Returns ablative.
Comment:
A very helpful function for items due to how few items use data and that it is parsed as an expression. You can put lists strings or numbers in there and you can get it in code.
Name:
itmGetTypes
Syntax:
(itmGetTypes criteria) -> list of itemUNIDs
Argument List:
criteria: a string that limits which items will be returned.
Returns:
a list of item UNID's containing all the items in game (including mods) that match the criteria specified
Category:
0.99, item
Description:
A list of item criteria can be found here:
http://wiki.neurohack.com/transcendence/wiki/modding/function/legend#item_criteria
Example:
Print the names of all weapons in game on the debug console:
[code](enum (itmGetTypes "w") itm (dbgOutput (itmGetName (itmCreate itm 1) 0)))[/code]
Comment:
* all categories
a armor
b miscellaneous devices (Patch Spider, Jumpdrive, Enhancers)
c cargo hold
d device (weapon, shield, drive, etc.)
f fuel
l launcher
m missile/ammo
r reactor
s shields
t miscellaneous
u useable (armor coating, ROM, etc.)
v drive
w weapon (including launchers)
I is installed
D is damaged
N is not damaged
S is usable
V is Virtual
U is not installed
Name:
itmGetUNID
Syntax:
(itmGetUNID item) -> itemUNID
Argument List:
item: The itemStruct of the item you want to get the UNID of.
Returns:
The UNID of the item.
Category:
deprecated, unid, item
Description:
Returns the UNID of the item.
Example:
[code](itmGetUNID (itmCreate 0x403E 1))[/code]
Returns the number 16446.
Comment:
DEPRECATED in 1.04: Use itmGetType instead
Basic get function for items. Useful for things that you need the UNID for like creating more of the same item or seeing if two itemstructs are the same kind of item.
Name:
itmGetUseScreen
Syntax:
(itmGetUseScreen item) -> screenUNID or Nil
Argument List:
item: The itemStruct of the item you want to get the use screen UNID from.
Returns:
The use screen UNID of the item, or Nil if it has none
Category:
item
Description:
Returns the use screen UNID of the item.
Example:
[code](itmGetUseScreen (itmCreate 0x403E 1))[/code]
Returns the number 0x0000A00D.
Comment:
Basic get function for items.
Name:
itmHasAttribute
Syntax:
(itmHasAttribute item attrib) -> True/Nil
Argument List:
item: The item you want to test
attrib: The attribute you want to test
Returns:
True if the 'item' contains the 'attrib', Nil otherwise
Category:
0.99, item, condition query
Description:
Checks if an item has a given attribute.
Example:
[code](itmHasAttribute (itmCreate &itLiquidOxygen; 1) "Volatile")[/code]
returns True
Comment:
Useful for seeing who produced what weapons for example. Look for the attributes Makayev, Rasiermesser, NAMI etc...
Name:
itmHasModifier_deprecated
Syntax:
(itmHasModifier_deprecated itemStruct string)
Argument List:
itemStruct: The itemStruct of the item you want to see if it has the modifier.
Returns:
condition: True if the item has the modifier Nil otherwise
Category:
0.98, item, deprecated
Description:
Finds out if the item has the modifier and returns the result.
DEPRECATED: Use itmHasAttribute instead.
Example:
[code](itmHasModifier (itmCreate 0x403E 1) 'ArmorEnhance)[/code]
Returns True.
Comment:
Useful if you are only checking for only one modifier. If looking for more use itmMatches.
Name:
itmHasReference
Syntax:
(itmHasReference item) -> True/Nil
Argument List:
item: The itemStruct of the item you want to test.
Returns:
boolean: True if the item is referenced, Nil otherwise.
Category:
item, condition query
Description:
Query function to see if the item is referenced.
Example:
[code](itmHasReference (itmCreate 0x4001 3))[/code]
Returns True. (level one items start out referenced).
Comment:
Basic query function for items. Referenced means it give the items info like damage and hp on the item listings.
Name:
itmIsDamaged
Syntax:
(itmIsDamaged item) -> True/Nil
Argument List:
item: The itemStruct of the item you want to check for damage.
Returns:
boolean: True if the item is damaged, Nil otherwise.
Category:
condition query, repair/damage, item
Description:
Returns whether the item is damaged or not.
Example:
[code](itmIsDamaged (itmCreate 0x4001 3))[/code]
Returns Nil. (well of course new items will not be damaged)
Comment:
Basic query function for items.
Name:
itmIsEnhanced
Syntax:
(itmIsEnhanced item) -> Nil or mods
Argument List:
item: The itemStruct of the item you want to get the enhancement status of.
Returns:
The enhancement flag if it is enhanced, Nil otherwise.
Category:
item, enhancement
Description:
Gets the enhancement flag for the item and returns it. For a list of enhancement flags, see
http://wiki.neurohack.com/transcendence/wiki/functionlegend#enhancements
Example:
[code](block (testArm)
(setq testArm (itmCreate 0x4001 1))
(itmSetEnhanced testArm 0x0105)
(itmIsEnhanced testArm)
)[/code]
Returns 261.
Comment:
Basic get function for items.
Name:
itmIsInstalled
Syntax:
(itmIsInstalled item) -> True/Nil
Argument List:
item: The itemStruct of the item you want to see if it is installed or not.
Returns:
condition: True if the item is installed, Nil otherwise.
Category:
item, condition query
Description:
Query function to see if the item is installed.
Example:
[code](itmIsInstalled (itmCreate 0x4001 3))[/code]
Returns Nil.
Comment:
Basic query function for items. Useful if you don't want to use the filters or itmMatches.
Name:
itmIsKnown
Syntax:
(itmIsKnown item) -> True/Nil
Argument List:
item: The itemStruct of the item you want to test.
Returns:
condition: True if the item is known, Nil otherwise.
Category:
item, condition query
Description:
Query function to see if the item is known. For more on known items, see here:
http://wiki.neurohack.com/transcendence/wiki/functionlegend#criteria
Example:
[code](itmIsKnown (itmCreate 0x4001 3))[/code]
Returns True. (you can't create unknown items in code.).
Comment:
Basic query function for items. Known means it is not an unknown item.
Name:
itmMatches
Syntax:
(itmMatches item criteria) -> True/Nil
Argument List:
item: The itemStruct of the item you want to test.
criteria: The criteria you want to test if the item matches.
Returns:
boolean: True if the item matches the criteria, Nil otherwise.
Category:
item, condition query
Description:
Query function to see if the item matches the criteria. For a description of criteria, see here:
http://wiki.neurohack.com/transcendence/wiki/functionlegend#criteria
Example:
[code](itmMatches (itmCreate 0x4173 1) "w +Alien;")[/code]
Returns True.
Comment:
Very useful and flexible query function for items. One nice use is separating out things without multiple enum.
Name:
itmSetCharges
Syntax:
(itmSetCharges item charges) -> item
Argument List:
item: the item whose charges you want to change
charges: the amount of charges you want to make the item have
Returns:
a new item, with the charges set. This item contains all other attributes of the original item
Category:
item, 0.99
Description:
Some items in game use charges to keep track of a certain value. This function can be used to set that value.
Example:
How to double the charges on Blue Credit Chip:
[code]
(block (creditChip charges)
(setq creditChip (itmCreate &itCashCardBlue; 1))
(setq charges (itmGetCharges creditChip))
(setq creditChip (itmSetCharges creditChip (multiply charges 2)))
)[/code]
This returns a new creditChip with double the amount of charges
Comment:
This is only useful for items that use charges. The amount of charges you specify will be what the item ends up with, so you have to use itmGetCharges first if you want to subtract charges.
Name:
itmSetCount
Syntax:
(itmSetCount item count) -> item
Argument List:
item: the item whose stack count you want to set
count: the count you want the item stack to have
Returns:
a new item, with the stack count you specified. You should use this item in place of the one you modified to keep the changes
Category:
item, 0.99
Description:
Every item in game exists in it's own little stack. Most items in game exist alone in their stack (ergo have a stack count of 1). All items in this stack are completely identical (including enhancements, damage, charges etc...)
This function is used to change the amount of items in a stack.
Example:
Create one Helium Fuel Rod, and then increase the item count in the stack to 100
[code]
(block (rod)
(setq rod (itmCreate &itHelium3FuelRod; 1))
(setq rod (itmSetCount rod 100))
)
[/code]
the rod variable starts containing a single Helium Rod and then gets increased to 100 fuel rods...
Comment:
Very useful for changing stack count without having to use itmCreate again.
Name:
itmSetDamaged
Syntax:
(itmSetDamaged itemStruct [boolean])
Argument List:
itemStruct: The item you want to create a damaged or undamaged version of.
boolean: An optional argument that if true makes the returned item damaged and if not makes it undamaged.
Returns:
itemStruct: The created item. Will be the same as the original item except will be damaged or not depending on the boolean.
Category:
repair/damage, item, 0.99
Description:
Creates a new item that is a copy of the passed in item except whether or not it is damaged. That is determined by the passed in boolean.
Example:
Comment:
This does nothing to the original item it only creates a new item with the wanted characteristics.
Name:
itmSetData
Syntax:
(itmSetData item attrib data [count]) -> item
Argument List:
item: the itemStruct to store data in
attrib: the key to set the data for
data: The data to be set on the item
[count]: the amount of items to set the data on
Returns:
item: the new item with the data on it
Category:
item
Description:
Allows for the storage of data on items.
Example:
[code]
(setq itm (itmCreate &itLaserCannon; 1))
(itmSetData itm "SomeKey" "SomeValue")
[/code]
Comment:
Useful for keeping track of specific values that are related to an item, for example, how many times it has been used. If you need to set data on an item stored on an object, you might consider using objSetItemData instead.
Name:
itmSetEnhanced
Syntax:
(itmSetEnhanced item mods) -> item
Argument List:
item: The itemStruct of the item you want to enhance.
flag: The flag saying what what type of enhancement you want to enhance the item with.
Returns:
item: The enhanced item.
Category:
enhancement, item
Description:
Enhances a item depending what kind of item it is and what is the flag.
The known list of flags can be seen here:
http://wiki.neurohack.com/transcendence/wiki/functionlegend#enhancements
Example:
[code](itmSetEnhanced (itmCreate 0x4001 1) 0x0B00)[/code]
Returns a segment of light titanium armor that is immune to radiation.
Comment:
Helpful for enhancing items you create. I need to make an enhancement list.
Name:
itmSetGlobalData
Syntax:
(itmSetGlobalData itemStruct string expression)
Argument List:
itemStruct: The item struct of the type you want to set global data to.
string: The name of the data you are setting.
expression: The value you want to be set.
Returns:
condition: True if successful.
Category:
0.99, data, item
Description:
Sets the given named data to what the value of the expression is.
Example:
Comment:
You can think of this as a helper function for typSetGlobalData
Name:
itmSetKnown
Syntax:
(itmSetKnown item [known]) -> True or Error
Argument List:
item: An itemStruct or the UNID of the item you want to make known.
known: True/nil. Default = true, makes item known. Nil makes item unknown.
Returns:
True if successful, or an Error if the argument is not an item
Category:
item
Description:
Makes the item known, if the item is unknown it turns it into its known type.
Does the reverse if 'known' is nil.
Example:
[code](itmSetKnown &itSystemMapROM;)
(itmSetKnown &itSRSDamageROM; nil)[/code]
Identifies all system map roms, while unidentifying defective visual display roms if they were known.
Comment:
"Known" is Transcendence's parallel to "identified"; unknown items have their stats and (randomized per game) name taken from another item as defined by their unknownType attribute.
The third argument and the ability to set items unknown were added in 1.04.
Name:
itmSetReference
Syntax:
(itmSetReference item) -> True or Error
Argument List:
item: The itemStruct of the item you want to make referenced.
Returns:
Almost always returns True. If passed a non-item arguement, it will return an Error
Category:
item
Description:
Makes the item referenced.
For more on referenced items, see here:
http://wiki.neurohack.com/transcendence/wiki/functionlegend#reference
Example:
[code](itmSetReference (itmCreate 0x4021 3))[/code]
Makes the Penitent cannon referenced.
Comment:
Referenced means it give the items info like damage and hp on the item listings.
Name:
lambda
Syntax:
(lambda args exp) -> lambda
Argument List:
args: A list of arguments you want to pass into the function. Can also be Nil.
exp: The code you want to pass the arguments to. It is not evaluated.
Returns:
The new function.
Category:
function operator
Description:
Function allowing you to create a function for later use.
Example:
[code](block (number fun)
(setq number 5)
(setq fun (lambda (adder)
(add 1 adder)
))
(dbgOutput number)
(setq number (fun number))
(dbgOutput number)
(setq number (fun number))
(dbgOutput number)
)[/code]
This displays on the debug console.
5
6
7
True
Comment:
The most important function in all of Transcendence. Allows the creation of functions to be stored and used later. Many creative things can be done with it.
Name:
leq
Syntax:
(leq a [b ... bn]) -> True if a <= b <= bn
Argument List:
a: The first expression you want to compare.
[b ... bn]: The next expressions you want to compare.
Returns:
boolean: The expressions are compared left to right. If there is any case where the left value is "greater" than the right value, `leq' will return Nil. Else it returns True.
Category:
logical operator
Description:
A comparison function that returns True if the left hand side is less than or equal to the right hand side. The same as <= in math.
Integers are compared by value, so (leq 1 1) -> True, but (leq 2 1) -> Nil
Strings are compared by alphabetical position, so (leq "a" "A") -> True, but (leq "b" "A") -> Nil
Lists are compared by length, so (leq '(2) '(1 1)) -> True, but (leq '(1 1) '(2)) -> Nil
Example:
[code](leq 7 3)[/code]
Returns Nil.
[code](leq "Betel" "Betelgeuse")[/code]
Returns True.
[code](leq '(a a b) '(c d e))[/code]
Returns True.
[code](leq "B" "b")[/code]
Returns True.
Comment:
Name:
list
Syntax:
(list i1 i2 ... in) -> list
Argument List:
i1: expression you want to be an element of the list.
i2 ... in: Expressions you want to be elements of the list
Returns:
A list of all the expressions passed as arguments.
Category:
list
Description:
Makes a list of the expressions in the order of the arguments.
Example:
[code](list 1 2 3 4)[/code]
Returns the list (1 2 3 4)
[code](block (vari)
(setq vari 5)
(list vari "list")
)[/code]
Returns the list (5 list)
Comment:
A nice helpful function for making lists.
Name:
lnkAppend
Syntax:
(lnkAppend list item) -> list
Argument List:
list: the list you want to append the expression to, as the last element.
item: The expression you want to append as the last element of the list.
Returns:
list; A list consisting of the first argument with the last argument appended to it.
Category:
list
Description:
Makes a new list made up of elements of the list then the expression and returns it.
Example:
[code](lnkAppend '(a b c) 2)[/code]
Returns the list (a b c 2)
Comment:
Very helpful in building lists in iteration functions.
Cannot take Nil as a list - only preexisting lists will do, so pass (list firstElement) instead of Nil.
Name:
lnkRemove
Syntax:
(lnkRemove list index) -> list
Argument List:
list: The list you want to remove the element at `index' from.
index: the position of the element you want to remove, counting from 0.
Returns:
A new list without the element found at `index'.
Category:
list
Description:
Removes the element at index and returns the resultant list.
Example:
[code](lnkRemove '(a b c d) 2 )[/code]
Returns the list (a b d)
Comment:
Another useful list function for the manipulation of lists and their elements.
This function CANNOT take itself as an argument, ie no (lnkRemove (lnkRemove list index) index2). This means removing multiple elements from a list requires multiple (setq (lnkRemove list index)) statements, one for every element to be removed.
Name:
lnkRemoveNil
Syntax:
(lnkRemoveNil list) -> list
Argument List:
list: The list where you want to remove all values that are Nil.
Returns:
A list with all the elements that equal Nil removed.
Category:
list
Description:
Goes through the list and removes all the Nil elements and returns the result.
Example:
[code](lnkRemoveNil '(a Nil (c Nil) Nil d))[/code]
Returns the list (a (c Nil) d).
Comment:
A bit of specific function. If you need it, use it.
Name:
lnkReplace
Syntax:
(lnkReplace list index item) -> list
Argument List:
list: The list in which you want to replace an element.
index: The position of the item in the list which you want to replace with a new item.
item: The item you want to place at `index'
Returns:
A list with the element at `index' replaced with the `item'.
Category:
list
Description:
Replaces a element at `index' and returns the resultant list. It also modifies the list in place.
Example:
[code](lnkReplace '(a b c d) 2 'e) -> (a b e d)[/code]
Modifying the list in place:
[code](setq l '(a b))
(lnkReplace l 0 'b)
l -> (b b)[/code]
Comment:
Very useful list function allowing you to change individual elements.
This function CANNOT take itself as an argument, ie no nesting (lnkReplace (lnkReplace list index item) index2 item2). This means replacing multiple elements in a list requires multiple (setq list (lnkReplace list index item)) statements in a row.
Name:
lookup
Syntax:
(lookup source target keyIndex) -> found entry
Argument List:
source: the list to do the lookup in
target: the key to find
keyIndex: the index in the source that the target will be looked for
Returns:
the found entry, if any (nil otherwise)
Category:
list
Description:
Useful for extracting lists within lists
Example:
[code]
(setq theList (list 1 'one) (list 2 'two))
(lookup theList 'one 1) -> (list 1 'one)
(lookup theList 2 0) -> (list 2 'two)
[/code]
Comment:
Name:
loop
Syntax:
(loop condition exp) -> value of last expression
Argument List:
condition: The function keeps on running as long as the condition is not Nil.
exp: The expression you want to evaluate as long as the condition is not Nil.
Returns:
Whatever the last evaluated expression returns.
Category:
iteration
Description:
Evaluates the expression over and over until the condition is Nil. The expression will never be evaluated if the condition starts as Nil.
Example:
[code](block (number)
(setq number 1)
(loop (ls number 5)
(block Nil
(setq number (add 1 number))
(dbgOutput number)
"yay"
)
)
)[/code]
Displays on the debug console.
2
3
4
5
Returns the string yay.
Comment:
Basic iteration function. Not as useful do to the more advanced iteration functions doing the things that you would do with a loop.
Name:
ls
Syntax:
(ls a [b ... bn]) -> True if a < b < bn
Argument List:
a: The first expression you want to compare.
[b ... bn]: The next expressions you want to compare.
Returns:
boolean: The expressions are compared left to right. If there is any case where the left value is "greater" than or equal to the right value, `ls' will return Nil. Else it returns True.
Category:
logical operator
Description:
kA comparison function that returns True if the left hand side is less than the right hand side. The same as < in math.
Integers are compared by value, so (ls 1 2) -> True, but (ls 1 1) -> Nil
Strings are compared by alphabetical position, so (ls "a" "b") -> True, but (ls "a" "A") -> Nil
Lists are compared by length, so (ls '(2) '(1 1)) -> True, but (ls '(1) '(2)) -> Nil
Example:
[code](ls 7 3)[/code]
Returns Nil.
[code](ls "Betel" "Betelgeuse")[/code]
Returns True.
[code](ls '(a a b) '(c d e))[/code]
Returns True.
[code](ls "B" "b")[/code]
Returns Nil.
Comment:
Name:
map
Syntax:
(map list variable expression) -> list
Argument List:
list: input list to work on
variable: name to use for each element in list
expression: code to run on each list item
Returns:
list: input list modified by expression
Category:
list, 1.04
Description:
Creates a new list made from the elements of the first list run through the expression
Example:
[code](map (list 1 2 3) it (add it 5))[/code]
Returns (6 7 8)
[code]
(setq outlist (list))
(enum (list 1 2 3) it
(lnkAppend outlist (add 5 it))
)
outlist
[/code]
What you'd have to do for the same result without map.
Comment:
General list managment and code simplification function.
Name:
match
Syntax:
(match list var boolean-exp) -> first item that matches
Argument List:
list: list of what you want to find a match in
var: a local variable used to store the current item in the list being checked agains the boolean expression.
boolean-exp: the expression to check the var against
Returns:
first item that matches
Category:
list
Description:
Allows one to find a match amongst a list.
Example:
[code]
(match (list 1 2 3 4 5) itm (eq (modulo itm 2) 0)))
[/code]
The above code returns 2 (it returns the first item in the list that is divisible by 2)
Comment:
Name:
max
Syntax:
(max expression [number]^1)
Argument List:
expression: A list or a number to find the greatest of.
number: One of the numbers that you want to find the greatest of.
Returns:
number: The greatest of the passed in numbers.
Category:
0.99, math
Description:
Finds and returns the greatest of the passed in numbers. If the first argument is a list of numbers that will be checked but no other arguments will be checked. Otherwise it will go through all the arguments.
Example:
[code](max 1 2 3 45) [/code]
Will return 45.
[code](max '(5 4 3 2 1)) [/code]
Will return 5.
Comment:
Nice quick function to find the greatest number from a list.
Name:
min
Syntax:
(min expression [number]^1)
Argument List:
expression: A list or a number to find the least of.
number: One of the numbers that you want to find the least of.
Returns:
number: Returns the least of the passed in numbers.
Category:
math, 0.99
Description:
Finds and returns the least of the passed in numbers. If the first argument is a list of numbers that will be checked but no other arguments will be checked. Otherwise it will go through all the arguments.
Example:
[code](min '(5 4 3 2 1))[/code]
Will return a 1.
[code] (min 34 54 784 4 45) [/code]
Will return a 4.
Comment:
Nice quick function to find the lowest number from a list.
Name:
modulo
Syntax:
(modulo number number)
Argument List:
number: The dividend of the two numbers.
number: The divisor of the two numbers.
Returns:
number: The remainder of the two numbers passed
Category:
0.99, math
Description:
Finds the remainder of the two numbers and returns it.
Example:
[code](modulo 56 34)[/code]
This code will return the number 22.
Comment:
Important for many things including bounding an arbitrary number between two numbers.
Name:
multiply
Syntax:
(multiply x1 [x2 ... xn]) -> z
Argument List:
x1: One of the integers you want to multiply.
[x2 ... xn]: The next integers you want to multiply.
^1
Returns:
z: The product of the numbers passed in
Category:
math, 0.99
Description:
Calculates the product of the arguments and returns it.
Example:
[code](multiply 56 34 2) -> 3808[/code]
Comment:
Basic math function that like all math functions are used all the time.
Name:
not
Syntax:
(not exp) -> True/Nil
Argument List:
exp: The expression you want to negate.
Returns:
condition: True if the expression evaluates to Nil, otherwise Nil.
Category:
logical operator
Description:
Returns the logical negation of the expression.
Example:
[code](not Nil) -> True
(not True) -> Nil
(not (eq 1 2)) -> True
(not (gr 2 1)) -> Nil[/code]
Comment:
Basic logical function to be used in conditionals.
Name:
objAccelerate
Syntax:
(objAccelerate obj angle thrust [ticks]) -> velVector
Argument List:
obj: the spaceobject to accelerate
angle: the angle to accelerate the spaceobject
thrust: the thrust to accelerate the spaceobject by
[ticks]: how many ticks the object is accelerated for
Returns:
velVector: the current velocity of the spaceObject.
Category:
spaceobject, vector operator
Description:
Used to accelerate a spaceObject by a certain factor, for an optional amount of time
Example:
Comment:
Not used in Transcendence.tdb
Name:
objAddBuyOrder
Syntax:
(objAddBuyOrder obj criteria priceAdj) -> True/Nil
Argument List:
obj: the targeted spaceobject
criteria: the itemCriteria string for the items to set a buy order for.
priceAdj: the adjusted price of whatever the object is going to pay for the item
Returns:
Boolean: true or nil depending upon success
Category:
spaceobject, economy
Description:
This function is used to add dynamic buy orders to objects (stations typically). The station will then purchase goods of the type specified in the criteria at the items price, adjusted by the specified price adjustment.
Used once, in &stManufacturingPlant;
Example:
[code]
(objAddBuyOrder someStation "* +Illegal" 150)
[/code]
Tell the station to buy illegal items at 150 precent
Comment:
useful for creating a dynamic economy
Name:
objAddItem
Syntax:
(objAddItem obj item [count]) -> True/Nil
Argument List:
obj: The spaceObject that you want to add the item to.
item: The itemStruct of the item you want to add.
[count]: An optional amount of items you want to add. It overrides the amount in the itemStruct
Returns:
boolean: True if successful, else Nil.
Category:
item, spaceobject
Description:
Adds the item to the space object. If number is there uses that many items otherwise uses the number of items in the itemStruct.
Example:
[code](objAddItem gplayerShip (itmCreate 0x4001 2))[/code]
Adds two segments of light titanium armor to the player ship.
[code](objAddItem gplayerShip (itmCreate 0x4001 3) 3)[/code]
Adds three segments of light titanium armor to the player ship.
[code](objAddItem gplayerShip (itmCreate 0x4001 2) 5)[/code]
Adds five segments of light titanium armor to the player ship. Remember the optional number over rides the number in the item struct.
Comment:
Very helpful function for adding non random items to a space object from code.
Name:
objAddItemEnhancement
Syntax:
(objAddItemEnhancement obj item enhancmentItemUnid [lifetime]) -> enhancementID
Argument List:
obj: spaceobject that holds the item to enhance
item: the item on the spaceobject to enhance
enhancementItemUnid: the enhancement to be applied onto the object (as used by george, unid of item with 'enhancement' attribute)
[lifetime]: how long the enhancement is to last
Returns:
enhancementID: the id of the applied enhancement. Used when removing the enhancement (if ever)
Category:
item, spaceobject
Description:
Allows for random enhancements, such as those seen with the crystals
Example:
Comment:
The enhancementType is an item with an 'enhancement' attribute on it.
a list on enhancement values is here:
http://wiki.neurohack.com/transcendence/wiki/functions/legend?s[]=enhancements#enhancements
Name:
objAddOverlay
Syntax:
(objAddOverlay obj overlayType [pos rotation] [lifetime]) -> overlayID
Argument List:
obj: spaceObject to apply overlay to
overlayType: UNID of to apply
pos: optional offset for graphical overlays
rotation: optional rotation for graphical overlays
[lifetime]: duration (in ticks?) after which to automatically delete overlay
Returns:
overlayID: a pointer to the live overlay
Category:
overlay, spaceobject
Description:
Creates a new overlay on the target ship. There are two variants of this function. One that sets a position and rotational offset from the center of the ship and one that does not. For both you can provide an optional lifetime.
Example:
From MiscItems.xml
[code]
; Find or create an overlay that will generate radioactive waste
(if (eq gSource gPlayerShip)
(block (theID)
(enum (objGetOverlays gSource) theOverlay
(if (eq (objGetOverlayType gSource theOverlay)
&ovUraniumWasteCheck; )
(setq theID theOverlay)
)
)
(if theID
(objIncOverlayData gSource theID "wasteCount"
(itmGetCount gItem)
)
(block Nil
(setq theID (objAddOverlay gSource &ovUraniumWasteCheck;))
(objSetOverlayData gSource theID "wasteCount"
(itmGetCount gItem)
)
(objSetOverlayData gSource theID "counter" 0)
)
)
)
)
[/code]
Comment:
Overlays can be used to modify incoming damage, display graphical effects, or execute code at regular intervals on a specific spaceobject. They have an OnUpdate event that is run every 15 ticks, not the customary 30
Name:
objAddRandomItems
Syntax:
(objAddRandomItems obj table count) -> True/Nil
Argument List:
obj: The spaceObject that you want to add the items to.
table: The itemTable UNID where you want to get the items from.
count: The number of times the itemtable is called.
Returns:
boolean: True if successful, else Nil.
Category:
spaceobject, random, item
Description:
Adds items to the space object according to the itemTable number of times.
Example:
[code](objAddRandomItems gplayership &trMinorItem6; 3)[/code]
Adds three random items to the gplayership according to the table &trMinorItem6;
Comment:
Very helpful function for adding random items to a space object from code.
Name:
objAddSellOrder
Syntax:
(objAddSellOrder obj criteria priceAdj) -> True/Nil
Argument List:
obj: spaceObject to add the sell order to
criteria: the item criteria string for the items to set a sell order for.
priceAdj: the percentage of the normal price to sell the items for
Returns:
Boolean: true/nil depending upon success
Category:
spaceobject, economy
Description:
Allows the selling of an item at an adjusted price.
Example:
taken from &ssBattleArena;
[code]
(objAddSellOrder gSource "*NU -Illegal; -ID; -NotForSale;" 130)
[/code]
Tells the station "gSource" to sell items that are not installed, undamaged, not illegal, not an ID and not having the NotForSale attribute at 130 percent of its normal value.
Supposedly returns true.
Comment:
useful for making a dynamic economy
Name:
objAddSubordinate
Syntax:
(objAddSubordinate obj subordinate) -> True/Nil
Argument List:
obj: The spaceObject that you want to add the subordinate too.
subordinate: The ship that you want to make subordinate to the `obj'.
Returns:
boolean: True if successful, Nil otherwise (like if the spaceObject is destroyed).
Category:
spaceobject, ship
Description:
Makes the ship a subordinate to the space object.
Example:
Comment:
To be used with staGetSubordinates. I am not sure of the exact nature of subordinates.
Name:
objCanAttack
Syntax:
(objCanAttack obj) -> True/Nil
Argument List:
obj: The spaceObject you want to test
Returns:
True if the spaceObject is capable of attacking, Nil otherwise.
Category:
condition query, spaceobject, 0.99
Description:
Some spaceObjects are not able to attack, mainly if they don't have any armament. This function is used to check that.
Example:
Comment:
Name:
objCanDetectTarget
Syntax:
(objCanDetectTarget obj target) -> True/Nil
Argument List:
obj: a spaceobject
Target: another spaceobject
Returns:
boolean: True or nil depending upon success
Category:
spaceobject
Description:
Tells is an object can target another object.
Example:
Comment:
Name:
objCharge
Syntax:
(objCharge obj [currency] amount) -> integer
Argument List:
obj: The spaceObject that you want to take credits away from.
[Currency]: the UNID of the currency
amount: The amount of credits you want to remove.
Returns:
integer: The remaining balance of the spaceObject you removed creadits from
Category:
cash, spaceobject, economy
Description:
Takes credits away from the the spaceObject.
Example:
[code](objCharge gSource 200)[/code]
Removes 200 credits from whatever gSource is bound too.
Comment:
Useful with working with the credits of stations. The player's credits are not bound to the player's ship.
Name:
objClearIdentified
Syntax:
(objClearIdentified obj) -> True/Nil
Argument List:
obj: spaceobject you want to clear the identification of
Returns:
boolean: true/nil depending on success
Category:
spaceobject
Description:
Transcendence has 3 functions for working with identification of objects. objIsIdentified, objSetIdentified and objClearIdentified.
Objects that the player has never seen are not identified by default.
Example:
Comment:
Name:
objClearShowAsDestination
Syntax:
(objClearShowAsDestination obj)
Argument List:
obj:spaceobject you want to clear from being the current destination
Returns:
boolean: true/nil depending on success
Category:
spaceobject
Description:
you can use objSetShowAsDestination to mark an object as the players current destination (with optional distance and bearing). Use this fuction to clear that destination.
Example:
taken from &stHereticControlCenter;
[code]
; Clear the destination target
(objClearShowAsDestination (objGetObjRefData gSource "target"))
[/code]
Comment:
Name:
objCommunicate
Syntax:
(objCommunicate spaceObject spaceObject number [spaceObject])
Argument List:
spaceObject: The space object that is sent the message.
spaceObject: The space object that sent the message.
number: The code of the message.
spaceObject: An optional space Object target needed by some codes.
Returns:
condition: True.
Category:
orders, spaceobject
Description:
A function that allows spaceobject to communicate and give orders to autons.
Example:
[code](objCommunicate gSource gplayership 14)[/code]
Tells the gSource auton that was communicated with by gplayership to wait.
Comment:
Only used with autons. Is not used with wing men.
The codes are:
1 = 'AttackTarget
2 = 'AttackTargetBroadcast
3 = 'HitByFriendlyFire
4 = 'QueryEscortStatus
5 = 'QueryFleetStatus
6 = 'EscortAttacked
7 = 'EscortReportingIn
8 = 'WatchYourTargets
9 = 'NiceShooting
10 = 'FormUp
11 = 'BreakAndAttack
12 = 'QueryComms
13 = 'AbortAttack
14 = 'Wait
15 = 'QueryWaitStatus
16 = 'AttackInFormation
17 = 'DeterTarget
18 = 'QueryAttackStatus
George really really really want to discourage us from using these code. Why? Because:
1. Not all controllers accept all codes. Auton, for instance, don't understand the 'AttackInFormation code. In general, unless you see the code being used, it will not work (or will not work correctly).
2. Some codes (such as 'AttackTargetBroadcast) only work when sent by stations that own the ships--sending the message through script may cause instability.
3. George is planning to deprecate the whole system. A better way to control autons and wingmen is to use the normal shpOrder functions--look at the implementation of Volkov, Jenna, and Rama for examples in RC1.
Name:
objCredit
Syntax:
(objCredit obj [currency] amount) -> integer
Argument List:
obj: The spaceObject that you want to give credits too.
[currency]: the UNID of the currency
amount: The amount of credits you want to give.
Returns:
integer: The new balance of the spaceObject you added credits to
Category:
cash, spaceobject, economy
Description:
Gives credits to the the obj.
Example:
[code](objCredit gSource 200)[/code]
Gives 200 credits from whatever gSource is bound too.
Comment:
Useful with working with the credits of stations. The player's credits are not bound to the player's ship.
Name:
objDamage
Syntax:
(objDamage obj weaponType objSource [posVector])
Argument List:
obj: spaceobject to damage
weaponType: the weapon UNID to use for the damage (there will be no shot effect)
objSource: a complex object describing the object doing the damage
[posVector]: a vector describing where to damage the object
Returns:
unsure
Category:
spaceobject, damage
Description:
There is a post by george on the forums best used to understand this function:
http://www.neurohack.com/transcendence/forums/viewtopic.php?p=40207#p40207
Example:
taken from: &ovPteravoreFuelDrain;
[code]
(objDamage gSource &vtPteravoreBite;
'("pteravores" 0x40)
(objGetOverlayPos gSource aOverlayID)
)
[/code]
Comment:
Name:
objDepleteShields
Syntax:
(objDepleteShields obj) -> True/Nil
Argument List:
obj: The spaceObject that you want to disable the shields of.
Returns:
boolean: True if successful, otherwise Nil
Category:
spaceobject, shield
Description:
A function that disables the shields of the spaceObject.
Example:
[code](objDepleteShields gPlayerShip)[/code]
Disables the players shields.
Comment:
Used in gem of sacrifice.
Name:
objDestroy
Syntax:
(objDestroy obj [objSource]) -> True/Nil
Argument List:
obj: The spaceObject that you want to destroy.
[objSource]: An optional spaceObject that destroys the other object.
Returns:
boolean: True if successful, otherwise Nil.
Category:
spaceobject
Description:
If used with only one argument it simply removes the spaceobject from the game. If the optional argument is provided, the function acts as if the target object was destroyed by the source, triggering any OnDestroy events, friend/enemy relations etc...
Example:
Assuming that the player has a ship targeted, this will destroy that target:
[code](objDestroy (objGetTarget gPlayerShip))[/code]
With the same assumption, this will destroy that target, and behave as if it was the player who did it:
[code](objDestroy (objGetTarget gPlayerShip) gPlayerShip)[/code]
Comment:
Can not be used on the player ship.
Name:
objEnumItems
Syntax:
(objEnumItems obj criteria itemVar exp) -> value of last expression
Argument List:
obj: The spaceObject whose items will be enumerated over.
criteria: The criteria of the items you want from the spaceObject.
itemVar: Name of the variable that will be used to hold the current item of the enumeration.
exp: The expression you want to evaluate for each item on the spaceObject matching the criteria. The item will be available inside the expression under the name you used in 'itemVar'.
Returns:
What the last expression in the iteration returns. In general the return value of an enumeration is not really interesting.
Category:
item, spaceobject, iteration
Description:
Allows you to run some code on every item on an object, one at a time. You can limit which items to enumerate over by using item criteria.
Iterates through the items in the space object that match the criteria. The variable will be available inside the function, holding the current item for each iteration.
Example:
[code]
(objEnumItems gPlayerShip "*wI" instWeap
(dbgOutput (itmGetName instWeap 0))
)[/code]
Outputs the name of all the installed weapons of the players ship to the debug console.
Comment:
Like all iteration functions very helpful for looping over a list of elements, in this case it is through the item list of a spaceObject.
Name:
objFireEvent
Syntax:
(objFireEvent obj event) -> result of event
Argument List:
obj: The spaceObject that has the event to be run.
event: The name of the event you want to run.
Returns:
Whatever the last run expression of the event returns. Nil if the event doesn't exist.
Category:
spaceobject, event
Description:
Runs any event on a spaceObject.
Example:
[code](objFireEvent gPlayerShip "testEvent")[/code]
Tries to run the event "testEvent" on the player ship. If it doesn't exist (like for the default player ships) it returns Nil.
Comment:
Great for triggering events from script. You can encapsulate some functionality in an event, and then use that event as if it were a function. It is also the only way of getting the return value of an event.
Name:
objFireItemEvent
Syntax:
(objFireItemEvent obj item event) -> result of event
Argument List:
obj: the spaceobject the event is to be invoked on
item: the item that has the event
event: event identifier
Returns:
result of event
Category:
spaceobject, events
Description:
used to call events off of items.
Example:
taken from &itQianlongArchcannon;
(objFireItemEvent gSource gItem "Recharge")
recharges the Quialong on an AI playership
Comment:
Name:
objFireOverlayEvent
Syntax:
(objFireOverlayEvent obj overlayID event) -> result
Argument List:
sObj: spaceOjbect the overlay is on
overlayID: the overlay to access
event: the event to trigger, string(?)
Returns:
result: return value of event code
Category:
overlay
Description:
Executes code from the section of the OverlayType related to the chosen overlay.
Example:
From CorporateHierarchy.xml
[code]
; Remove any overlays that shouldn't be there (e.g., pteravores)
(enum (objGetOverlays gPlayerShip) theOverlay
(objFireOverlayEvent gPlayerShip theOverlay "OnInsuranceClaim")
)
[/code]
From EncountersVol01.xml
[code]
; Insurance cleans up pteravores
(objRemoveOverlay gSource aOverlayID)
[/code]
Comment:
Name:
objFixParalysis
Syntax:
(objFixParalysis obj)
Argument List:
obj: the spaceobject to paralyze
Returns:
boolean: true/nil depending upon success
Category:
spaceobject
Description:
Is counterpart to objMakeParalyzed.
Example:
[code](objFixParalysis gPlayership)[/code]
returns true if playership was paralysed (and removes the paralysis)
Comment:
Name:
objGateTo
Syntax:
(objGateTo obj node entrypoint [effectID])
Argument List:
obj: The spaceObject you want to gate somewhere.
node: The node id of the system you want to gate to.
entrypoint: The label in the system you want to go to. This label can be hardcoded in xml, or usually one of the two labels Inbound/Outbound can be used.
[effectID]: The UNID of the effect you want to use when you gate.
Returns:
True. This return value can mostly be ignored
Category:
spaceobject
Description:
Gates the spaceObject to whatever system you want. The 'entrypoint' is a bit tricky, since it must be hardcoded in the systems xml description to be used here. If there is a gate leading into the system, "Inbound" can usually be used, if there is a gate leading out, "Outbound" can be used. The list returned from sysGetStargates contains valid labels.
Example:
[code](objGateTo gPlayerShip "Elysium" "Start" &efStargateOut;)[/code]
Gates the player ship to Elysium and puts the ship at the start label.
Comment:
Fairly obvious function but can be used to mimic stargates. It requires the use of a valid label, which can be a bit clunky to get. Dynamic labels would be a big addition...
Name:
objGetArmorDamage
Syntax:
(objGetArmorDamage spaceObject number)
Argument List:
spaceObject: The space object that you want to get the damage of the armor from.
number: The segment number of the armor of the space object from what you want to get the damaged from.
Returns:
number: The amount of damage the armor has.
Category:
repair/damage, spaceobject, armor
Description:
Returns the amount of damage on the armor segment on the space object.
Example:
[code](objGetArmorDamage gPlayerShip 0)[/code]
Returns the amount of damage on the forward armor.
Comment:
Basic function for getting the armor damage from a space object.
Name:
objGetArmorLevel
Syntax:
(objGetArmorLevel obj item|armorSegment) -> 0-100
Argument List:
obj: the spaceobject
Item|ArmorSegment: armorsegment to check
Returns:
number: 1-100
Category:
spaceobject, item, armor
Description:
Allows the checking of the armor's /hp/ level, not actual level
Example:
[code](objGetArmorLevel gSource gItem)
[/code]
will return 100 if the armor is undamaged.
A nice in-game example is &itOmskDeflectorI; in the event
Comment:
Name:
objGetArmorName
Syntax:
(objGetArmorName spaceObject number)
Argument List:
spaceObject: The space object that you want to get the name of the segment of.
number: The segment number that you want to get the name of.
Returns:
string: The name of the segment.
Category:
name, armor, spaceobject
Description:
Returns the name of the segment.
Example:
[code](objGetArmorName gPlayerShip 0)[/code]
Returns the string forward.
Comment:
A bit misleading name but it basically just gets the armor sections name. Maybe objGetArmorSectionName would work better.
Name:
objGetArmorType
Syntax:
(objGetArmorType spaceObject number)
Argument List:
spaceObject: The space object that you want to get the type of armor from.
number: The segment number that you want to get the name of.
Returns:
ArmorType: The armor type of the armor at that segment.
Category:
armor, spaceobject
Description:
Returns the armortype of the armor segment.
Example:
[code](objGetArmorType gPlayerShip 0)[/code]
Returns the armor type of the player ships forward armor.
Comment:
Evil function that will hopefully will be fazed out.
Name:
objGetBalance
Syntax:
(objGetBalance spaceObject [currency]) -> number
Argument List:
spaceObject: The space object that you want to get the amount of credits from.
[Currency]: the UNID of the currency
Returns:
number: The amount of credits that the space object has.
Category:
cash, spaceobject, economy
Description:
Returns the amount of credits the space object has.
Example:
[code](objGetBalance gsource)[/code]
Returns the amount of credits that the caller has.
Comment:
Useful function but be aware that the players credits are not tied to the player's ship.
Name:
objGetBuyPrice
Syntax:
(objGetBuyPrice spaceObject itemStruct)
Argument List:
spaceObject: The space object that you want to get the buying price of.
itemStruct: The itemStruct of the item that you want to get the price of.
Returns:
number: The amount that this space object will sell the item for.
Category:
item, spaceobject, cash
Description:
Finds the cost it would cost to buy the item from the space object and returns it.
Example:
[code](objGetBuyPrice gSource (itmCreate 0x4001 1))[/code]
Returns the price of a light titanium armor for the calling object.
Returns 0 for items the station is not interested in; it returns Nil for items that are not listed. (from 0.99)
Comment:
For the gplayership returns Nil. Also remember the buy in it means from the players point of view not the spaceobjects.
Name:
objGetCargoSpaceLeft
Syntax:
(objGetCargoSpaceLeft spaceObject)
Argument List:
spaceObject: The space object that you want to get the cargo space left of.
Returns:
number: The amount of space left in the cargo bay.
Category:
spaceobject
Description:
Returns the amount of cargo space left in the space object.
Example:
[code](objGetCargoSpaceLeft gplayerShip)[/code]
Returns the amount of space left in the players ship.
Comment:
All* ships have a max cargo space defined in the XML, but any ship can go over this limit if items are placed on the ship without checking this function and respecting inventory limits manually.
( * Verify ... also, I'm not sure if the NPC looting functions like the commonwealth traffic scuttle-looting or the salavager code respects inventroy limits. --Weaver 2012 June)
Name:
objGetCombatPower
Syntax:
(objGetCombatPower spaceObject)
Argument List:
spaceObject: The space object that you want to get the combat power of.
Returns:
number: A number between 1 and 100 representing the combat power of the space object.
Category:
spaceobject
Description:
Returns the combat power the space object.
Example:
Comment:
I am not sure how this is calculated.
Name:
objGetDamageType
Syntax:
(objGetDamageType spaceObject)
Argument List:
spaceObject: The thing you want to know the damage type of.
Returns:
number: The damage type.
Category:
spaceobject
Description:
Returns the damage type of the object.
Example:
Comment:
Used to get the damage type of an objects current primary weapon.
Damage types are returned as numbers and are:
0 - Laser
1 - Kinetic
2 - Particle
3 - Blast
4 - Ion
5 - Thermo
6 - Positron
7 - Plasma
8 - Antimatter
9 - Nano
10 - Graviton
11 - Singularity
12 - DarkAcid
13 - DarkSteel
14 - DarkLightning
15 - DarkFire
Name:
objGetData
Syntax:
(objGetData spaceObject string)
Argument List:
spaceObject: The space object you want the data from.
string: The name of the data you want.
Returns:
The data named by the string from the space object. Returns Nil if there is no data as named by the string.
Category:
spaceobject, data
Description:
Returns the data named by the string for the space object.
Example:
[code](objGetData gPlayerShip "rins")[/code]
Returns the rins from the players ship. This is how the game handles rins.
Comment:
Very useful in getting information stored on an space object from code. If you want data from the xml look at the function objGetStaticData.
Name:
objGetDataField
Syntax:
(objGetDataField obj field) -> data
Argument List:
obj: the spaceobject the data is in
field: the identifier of the data
Returns:
data: the data found in the field
Category:
spaceobject, data
Description:
a list of data fields can be found here:
http://wiki.neurohack.com/transcendence/wiki/modding/function/legend#data_fields
Example:
Comment:
Name:
objGetDefaultCurrency
Syntax:
(objGetDefaultCurrency obj) -> currency
Argument List:
obj: the spaceobject to check default currency for
Returns:
currency: the UNID of the default currency
Category:
economy, 1.06
Description:
used to get the default currency of an object
Example:
Comment:
Name:
objGetDestiny
Syntax:
(objGetDestiny spaceObject)
Argument List:
spaceObject: The space object you want the destiny of.
Returns:
number: A number from 0 to 359
Category:
spaceobject
Description:
Returns the destiny code of the space object.
Example:
Comment:
Destiny is a random number generated for each spaceObj when the Obj is created. For the playership, it changes every time the player starts a new game.
Name:
objGetDeviceFireArc
Syntax:
(objGetDeviceFireArc obj deviceItem) -> (minArc maxArc)
Argument List:
obj: the spaceobject that has the devices
deviceItem: the item to check for arcs
Returns:
list: two numbers, the min arc then the max arc
Category:
1.06, spaceobject, weapon
Description:
can be used to retrieve the min and max firearc if it was set by objSetDeviceFireArc.
Example:
Comment:
Not used in Transcendence.tdb
Returns (0 0) if firearcs were set by MinFireArc= and MaxFireArc=
Name:
objGetDevicePos
Syntax:
(objGetDevicePos obj deviceItem) -> (angle radius)
Argument List:
obj:
deviceItem:
Returns:
(angle radius): two numbers, the angle and radius that points to the device location on the ship
Category:
spaceobject, item
Description:
Allows for retrieval of device positions. Default is (0 0) but can be set to other values using objSetDevicePos. Unsure what the effects of using objSetDevicePos on miscellaneous items though.
Example:
Not used in Transcendence.tdb
Comment:
Name:
objGetDisposition
Syntax:
(objGetDisposition obj targetObj) -> disposition of obj towards targetObj
Argument List:
obj: an object
TargetObj: the spaceobject to test disposition towards
Returns:
disposition of obj towards targetObj
Category:
spaceobject
Description:
Dispositions are:
friendly
neutral
enemy
Example:
[code]
(block Nil
(dbglog (objGetDisposition gSource (ObjGetTarget gSource)))
)
[/code]
Put this invoke in a weapon and it will both playermessage and debug log the disposition when invoked "[U]sed".
Comment:
Name:
objGetDistance
Syntax:
(objGetDistance spaceObject spaceObject)
Argument List:
spaceObject: The space object you want to find the distance from.
spaceObject: The space object you want to find the distance to.
Returns:
number: The distance between the two space objects.
Category:
spaceobject
Description:
Returns the distance between the two space objects.
Example:
[code](objGetDistance gPlayerShip gsource)[/code]
Returns the distance between the calling space object and the player ship.
Comment:
Helpful little function if you want something to happen only when the player is close enough.
Name:
objGetEventHandler
Syntax:
(objGetEventHandler obj) -> unid or Nil
Argument List:
obj: the target spaceobject
Returns:
UNID of eventhandler, or nil, if none
Category:
spaceobject
Description:
Useful for checking if a spaceobject has an event handler.
Example:
not used in Transcendence.tdb
Comment:
Name:
objGetGlobalData
Syntax:
(objGetGlobalData spaceObject string)
Argument List:
spaceObject: The space object belonging to the class you want the data from.
string: The name of the data you want.
Returns:
The data named by the string from the space objects class. All space objects in the same class share the same global data. Returns Nil if there is no data as named by the string.
Category:
spaceobject, data
Description:
Returns the data named by the string for the space objects class.
Example:
Comment:
Basically the same as objGetData except all space object in the same class share the same data.
Name:
objGetID
Syntax:
(objGetID spaceObject)
Argument List:
spaceObject: The space object you want to find the ID of.
Returns:
number: The ID of the space object.
Category:
spaceobject
Description:
Returns the ID of the space object.
Example:
Comment:
This isn't the UNID. The ID is a number that uniquely identifies a spaceObject in the whole explored universe. (to get a ID, the spaceObject must be first created, of course)
The function is currently used only for the Sung slavers.
This function is used in conjunction with objGetObjByID.
Name:
objGetImageDesc
Syntax:
(objGetImageDesc spaceObject) => (List)
Argument List:
spaceObject: the spaceobject that you want the details of the image used.
Returns:
list: a list of 5 numbers, the first is the UNID of the image resource as a number, the second and the third are the x,y coordinates in pixels of the resource image (from the top left corner of the image) the fourth and fifth are the sizes of the resource image in pixels. (first width then height)
Category:
0.99, spaceobject, unid
Description:
Returns details on the resource image used by a spaceObject.
Example:
[code](objGetImageDesc gPlayership)[/code]
returns (61757 0 0 64 64) if the player is using the Freighter.
Comment:
Helpful function for image resource management.
Name:
objGetInstalledItemDesc
Syntax:
(objGetInstalledItemDesc spaceObject itemStruct)
Argument List:
spaceObject: The space object that the item is in.
itemStruct: The itemstruct of the item that you want the installed description of.
Returns:
string: The installed description of the item.
Category:
spaceobject
Description:
Creates and returns a string describing how the item is installed.
Example:
Comment:
Kind of hard to describe. Take for example armors they have locations so a forward armor would return "installed as forward armor".
Name:
objGetItems
Syntax:
(objGetItems spaceObject criteria)
Argument List:
spaceObject: The space object that the items are in.
criteria: The criteria that you want the items you get to match.
Returns:
list: A list of all the items in the space object that match the criteria.
Category:
spaceobject, item
Description:
Creates and returns a list of all the items in the space object that match the criteria.
Categories can be seen here:
http://transcendence.kronosaur.com/wiki/modding/function/legend#item_criteria
Example:
[code](objGetItems gplayerShip "wI")[/code]
Returns a list of all the installed weapons on the ship.
Comment:
Useful for getting all the items of a certain kind from a space object. It is most often used to check if the space object contains a certain kind of items.
Name:
objGetLevel
Syntax:
(objGetLevel obj) -> level
Argument List:
obj: The spaceObject you want to get the level of
Returns:
level: an integer representing the level of the object
Category:
spaceobject
Description:
easy to use function to get the level of an object in the current system
Example:
[code](objGetLevel (objGetTarget gPlayerShip))[/code]
Returns the level of the player current target
Comment:
Name:
objGetMass
Syntax:
(objGetMass spaceObject)
Argument List:
spaceObject: The space object that you want the mass from.
Returns:
number: the mass of the spaceobject and all of its cargo expressed in tons.
Category:
spaceobject, 0.99
Description:
Returns the mass of the spaceobject and all of its cargo.
Example:
[code](objGetMass gPlayership)[/code]
Returns the total mass of the playership.
Comment:
Basic space object function to get the space objects mass.
Name:
objGetMaxPower
Syntax:
(objGetMaxPower spaceObject)
Argument List:
spaceObject: The space object that you want the max power from.
Returns:
number: The max power of the space object in tenth-megawatts (10^5 watts).
Category:
reactor, spaceobject
Description:
Returns the max power of ship space object.
Example:
[code](objGetMaxPower gplayerShip)[/code]
Returns the max power of the currently equipped reactor.
Comment:
In the core game, this function is only used in various dock services panels to determine what the next level of reactor upgrade you should get is.
The tenth-megawatt scale is the same as what's used in the definiton.
Name:
objGetName
Syntax:
(objGetName spaceObject [number]) -> string
Argument List:
spaceObject: The space object that you want the name from.
[number]: An optional naming code
Returns:
string: The name of the space object.
Category:
spaceobject, name
Description:
Returns the name of space object. You must provide a flag to indicate how you want the name formatted. For more on flags, see:
http://wiki.neurohack.com/transcendence/wiki/functionlegend#name_flags
Example:
[code](objGetName gplayerShip)[/code]
Returns the name of the player ship.
[code](objGetName gplayerShip 2)[/code]
Returns the pluralized name of the player ship.
Comment:
Basic space object function to get the space objects name.
[number] can be:
1 = capitalize
2 = pluralize
4 = prefix with 'the' or 'a'
8 = prefix with count
Name:
objGetNamedItems
Syntax:
(objGetNamedItems obj name)
Argument List:
obj: obj you want to get weapon of
name: string defining what item you want to get
Returns:
list
Category:
1.0, item, spaceobject
Description:
Returns data on one of the ships selected weapons
Example:
Comment:
If name == 'selectedWeapon, returns a list of one item, where the item is the selected weapon.
If name == 'selectedLauncher, returns a list of one item, where the item is the currently installed launcher.
If name == 'selectedMissile, returns a list of one item, where the item is the selected missile. Returns Nil if no missiles installed. If the launcher does not use missiles (e.g., DM600), then returns the installed launcher.
Name:
objGetNearestStargate
Syntax:
(objGetNearestStargate spaceObject)
Argument List:
spaceObject: The space object that you want to get the nearest star gate from.
Returns:
spaceObject: The nearest star gate.
Category:
spaceobject
Description:
Returns the nearest star gate to the space object.
Example:
[code](objGetNearestStargate gplayerShip)[/code]
Returns the nearest star gate to the player ship.
Comment:
Used main to create ships from the nearest star gate or to find the distance to the nearest star gate.
Name:
objGetObjByID
Syntax:
(objGetObjByID number)
Argument List:
number: the ID of the spaceObject that uniquely identifies it.
Returns:
spaceObject: the spaceobject with the unique ID.
Category:
0.99, spaceobject
Description:
Returns the spaceObj of the unique ID passed into the function.
Example:
Comment:
This function works in conjunction with objGetID.
The ID is not the UNID. It's a number that uniquely identifies an already created spaceObject.
objGetObjByID works only if the spaceObj is in the same system as the calling spaceObj.
Name:
objGetObjRefData
Syntax:
(objGetObjRefData spaceObject string)
Argument List:
spaceObject: The space object that you want to get the space object reference from.
string: The name of the space object reference.
Returns:
spaceObject: The space object in this space object that is named by the string.
Category:
spaceobject
Description:
Returns the space object reference stored in this space object named by the string.
Example:
Comment:
Used with objSetObjRefData. Just like objGetData except it can get space objects.
Name:
objGetOpenDockingPortCount
Syntax:
(objGetOpenDockingPortCount obj) -> count of open docking ports
Argument List:
obj: the spaceobject to check the number of open dockingports
Returns:
Number: count of open docking ports
Category:
spaceobject
Description:
Used only by Korolov Shipping as a check to get more freighters.
Example:
Comment:
Name:
objGetOrderGiver
Syntax:
(objGetOrderGiver spaceObject)
Argument List:
spaceObject: The space object that you want to get the order giver from.
Returns:
spaceObject: The order giver.
Category:
orders, spaceobject
Description:
Gets the space object that gave a order to the passed in space object.
Example:
[code](eq (objGetOrderGiver gsource) gPlayerShip)[/code]
Returns whether the calling space object has been given an order by the player ship.
Comment:
Helpful little function if you need to know who gave an order to a ship.
Name:
objGetOverlayData
Syntax:
(objGetOverlayData sObj overlayID attrib) -> data
Argument List:
sObj: spaceOjbect the overlay is on
overlayID: the overlay to access
attrib: the name of the data attribute to work with
Returns:
data: whatever was previously set with objGetOverlayData
Category:
overlay
Description:
Gets arbitray data from a specific overlay on a spaceobject.
Example:
Comment:
Analogous to objGetData.
Name:
objGetOverlayPos
Syntax:
(objGetOverlayPos sObj overlayID) -> vector
Argument List:
sObj: spaceOjbect the overlay is on
overlayID: the overlay to get the position of
Returns:
vector: the position (relative to the spaceobject?)
Category:
overlay
Description:
Returnst he position of the overlay, as set in objAddOverlay.
Example:
From EncountersVol01.xml
[code]
; Do damage
(setq result (objDamage
gSource
&vtPteravoreBite;
'("pteravores" 0x40)
(objGetOverlayPos gSource aOverlayID)
))
[/code]
Damages hosts ship's armor segment which corresponds to the position of the overlay.
Comment:
Name:
objGetOverlayRotation
Syntax:
(objGetOverlayRotation sObj overlayID) -> rotation
Argument List:
sObj: spaceOjbect the overlay is on
overlayID: the overlay to access
Returns:
rotation: current orientation of overlay
Category:
overlay
Description:
Gets the current facing of the overlay. For graphical coverlays.
Example:
Comment:
Not used in TranscendenceSource 1.04
Name:
objGetOverlays
Syntax:
(objGetOverlays sObj) -> overlayIDs
Argument List:
sObj: spaceObject to get overlays from
Returns:
overlayIDs: list of overlay IDs suitable for use in other overlay functions
Category:
overlay
Description:
Returns list of active overlays currently on the object.
Example:
From CorporateHierarchy.xml
[code]
; Remove any overlays that shouldn't be there (e.g., pteravores)
(enum (objGetOverlays gPlayerShip) theOverlay
(objFireOverlayEvent gPlayerShip theOverlay "OnInsuranceClaim")
)
[/code]
Comment:
Name:
objGetOverlayType
Syntax:
(objGetOverlayType obj overlayID) -> type
Argument List:
obj: the spaceobject to check for overlays
overlayIDs: list of overlay IDs suitable for use in other overlay functions
Returns:
Type: returns the UNID of the overlay
Category:
spaceobject, overlay
Description:
Useful for checking if an overlay already exists on a ship.
Example:
Comment:
Surprisingly, not used by the pteravores, but by the Uranium Fuel Rods (&itUraniumRods;).
Name:
objGetPos
Syntax:
(objGetPos spaceObject)
Argument List:
spaceObject: The space object that you want the position of.
Returns:
vector: The position of the space object.
Category:
spaceobject
Description:
Returns the vector position of the space object.
Example:
[code](objGetPos gPlayerShip)[/code]
Returns the vector position of where in the system the player ship is.
Comment:
Helpful little function if you need to know where a space object is for later use.
Name:
objGetSellPrice
Syntax:
(objGetSellPrice spaceObject itemStruct)
Argument List:
spaceObject: The space object that you want to get the selling price of.
itemStruct: The itemStruct of the item that you want to get the price you can sell it at.
Returns:
number: The amount that this space object will buy the item for.
Category:
cash, item, spaceobject
Description:
Finds the amount the space object would pay for the item.
Example:
[code](objGetSellPrice gSource (itmCreate 0x4001 1))[/code]
Returns the price that it would buy a light titanium armor for the calling object.
Comment:
For the gplayership returns Nil. Also remember the sell in it means from the players point of view not the spaceobjects.
Name:
objGetShieldLevel
Syntax:
(objGetShieldLevel spaceObject)
Argument List:
spaceObject: The space object that you want to get the shield level of.
Returns:
number: The amount of shield left divided by the max amount of shield on the space object. Returns -1 if no shield is equipped.
Category:
spaceobject, shield
Description:
Finds and returns the percent of shield remaining.
Example:
[code](objGetShieldLevel gplayership)[/code]
Returns the percent of shield remaining.
Comment:
This is also a shortcut to see if the object has a shield equipped.
Name:
objGetShipwreckType
Syntax:
(objGetShipwreckType shipwreck) -> UNID
Argument List:
shipwreck: spaceObject of a wrecked ship
Returns:
UNID: ID of ShipType that wreck was before it was a wreck, or Nil if it's not a shipwreck
Category:
1.04, spaceobject
Description:
Returns the ShipType UNID of the ship that caused a wreck
Example:
[code]
(typGetDataField
(objGetShipwreckType (objGetTarget gPlayership))
'name
)
[/code]
Returns the name of the ship that caused the shipwreck that the player is targetting, for example, "Centauri raider"
Comment:
Particuarly useful with gSource inside the shipwreck dockscreen.
Name:
objGetSovereign
Syntax:
(objGetSovereign spaceObject)
Argument List:
spaceObject: The space object that you want to get the sovereign of.
Returns:
number: The UNID of the sovereign.
Category:
spaceobject, ai, unid
Description:
Finds and returns sovereign of the space object.
Example:
[code](objGetSovereign gplayership)[/code]
Returns 4097.
Comment:
Basic space object function.
Name:
objGetStaticData
Syntax:
(objGetStaticData spaceObject string)
Argument List:
spaceObject: The space object of the type you want to get the static data from.
string: The name of the static data.
Returns:
data: The data from the xml named by the string from the space objects type.
Category:
spaceobject, data
Description:
Returns the data from the xml named by the string from whatever the space objects type is.
Example:
Comment:
Very useful function due to you can store things in the xml before hand and get them in code.
Name:
objGetStaticDataForStationType_deprecated
Syntax:
(objGetStaticDataForStationType_deprecated number string)
Argument List:
number: The UNID of the station you want to get the static data from.
string: The name of the static data.
Returns:
data: The data from the xml named by the string from the space object type.
Category:
station, data, unid, 0.98
Description:
Returns the data from the xml named by the string from the space objects type.
Example:
Comment:
Just like objGetStaticData except it takes a UNID instead of a space object. Very useful function due to you can store things in the xml before hand and get them in code.
DEPRECATED. Use typGetStaticData instead.
Name:
objGetTarget
Syntax:
(objGetTarget spaceObject)
Argument List:
spaceObject: The space object you want to get the current target of.
Returns:
spaceObject: The target of the space object.
Category:
spaceobject
Description:
Returns the target of the space object.
Example:
[code](objGetTarget gsource)[/code]
Returns the target of the calling space object.
Comment:
Can be useful in case you want to do things by what the player is targeting.
Name:
objGetType
Syntax:
(objGetType obj) -> unid
Argument List:
obj: the spaceobject you want to get the UNID of
Returns:
UNID: the UNID of the spaceobject
Category:
spaceobject
Description:
The function to use to get the UNID of a spaceobject
Example:
Taken from &stCommonwealthSlums;
[code]
(eq (objGetType gPlayerShip) &scSapphirePlayer;)
"My daughter's friend had one once.
It was beautiful, but not very practical for long voyages.\""
[/code]
Comment:
Name:
objGetVel
Syntax:
(objGetVel spaceObject)
Argument List:
spaceObject: The space object you want to get the current velocity of.
Returns:
velVector: the current velocity of the spaceObject.
Category:
vector operator, 0.99, spaceobject
Description:
Returns the velocity vector of the spaceObject.
Example:
Comment:
A basic function for manipulating the speed of a spaceObject.
Name:
objGetVisibleDamage
Syntax:
(objGetVisibleDamage spaceObject)
Argument List:
spaceObject: The space object you want to get the most damaged armor damage percent.
Returns:
number: The percent of damage the most damaged armor on the space object.
Category:
repair/damage, spaceobject
Description:
Returns the percent of damage the most damaged armor on the space object.
Example:
[code](objGetVisibleDamage gplayership)[/code]
Returns the percent of damage the most damaged armor on the players ship.
Comment:
It would seem that it is almost the same thing as used by the targeting info damage percent.
Name:
objHasAttribute
Syntax:
(objHasAttribute spaceObject string)
Argument List:
spaceObject: The space object you want to see if it has the attribute.
string: The attribute's that you want name.
Returns:
condition: True if the space object has that attribute. Nil otherwise.
Category:
spaceobject, condition query
Description:
Checks to see if the space object has the attribute named by the string.
Example:
[code](objHasAttribute gSource "pirates")[/code]
Checks to see if the space object has the attribute pirates.
Comment:
Very helpful function if you want to find a certain group of ships/stations.
Name:
objHasItem
Syntax:
(objHasItem source item [count]) -> number of items (or Nil)
Argument List:
source: The spaceObject you want to test for presence of the item.
item: The itemStruct you want to test if the object has
[count]: an optional minimum amount of items to check for
Returns:
if the object has any of the items checked for, then it returns the count. If it has none, then it returns Nil. If [count] has been specified and the object does not have that amount, Nil is returned, else the amount is returned.
Category:
condition query, spaceobject
Description:
Useful to see if and how many of an item an object has. Note that item must be an itemStruct, that is, it must be created using (itmCreate ...) or gathered in some other manner
Example:
[code](objHasItem gplayership (itmCreate &itHelium3FuelRod; 1) 10)[/code]
Checks to see if the player ship has at least 10 Helium Fuel ROds.
Comment:
Name:
objIncData
Syntax:
(objIncData spaceObject string [number])
Argument List:
spaceObject: The space object you want to alter a numerical data in.
string: The name of the data you want to alter.
[number]: The amount you want to add to the data. If this value is left out, then the value 1 is automatically used.
Returns:
condition: True if successful.
Category:
data, spaceobject
Description:
Adds the number to the data in the space object named by the string.
Example:
[code](objIncData gPlayerShip "rins" 100)[/code]
Adds 100 rins to the player.
[code](objIncData gPlayerShip "rins")[/code]
Add 1 rin to the player.
Comment:
Basically a helper function so you don't have to do set and add all the time.
Name:
objIncItemCharges
Syntax:
(objIncItemCharges obj item [increment] [count]) -> itemStruct
Argument List:
obj: the desired spaceobject
item: the desired item to increase
[increment]: a number to manipulate charges by
[count]: the amount of items in the itemStruct you want to change
Returns:
itemStruct: the modified item
Category:
spaceobject, item
Description:
Used to modify the amount of charges in an item.
Example:
Comment:
Name:
objIncOverlayData
Syntax:
(objIncOverlayData sObj overlayID attrib [increment]) -> newValue
Argument List:
sObj: spaceOjbect the overlay is on
overlayID: the overlay to access
attrib: the name of the data attribute to work with
[increment]: number to add to value that is already there
Returns:
newValue: the value that the attribute was set to
Category:
overlay
Description:
Shortcut function that adds a value to an overlay attribute without having to get the attribute first.
Example:
From MiscItems.xml
[code]
; Create a barrel of waste every 90 cycles (45 seconds)
(if (geq (objIncOverlayData gSource aOverlayID "counter") 90)
(block (left)
(setq left (objIncOverlayData gSource aOverlayID "wasteCount" -1))
(objAddItem gSource (itmCreate &itRadioactiveWaste; 1))
(objSetOverlayData gSource aOverlayID "counter" 0)
(plyMessage gPlayer "Uranium rod consumed")
(if (eq left 0)
(objRemoveOverlay gSource aOverlayID)
)
)
)
[/code]
Comment:
Not sure what it does when increment is not provided.
Name:
objIncVel
Syntax:
(objIncVel spaceObject vector)
Argument List:
spaceObject: The space object you want to alter a numerical data in.
vector: The vector you want to change the space object velocity by.
Returns:
velVector: returns the new velocity vector.
Category:
vector operator, spaceobject
Description:
Adds the number to the data in the space object named by the string.
Example:
[code](objIncVel gPlayerShip (sysVectorPolarVelocity
(shpgetDirection gPlayerShip) 10))[/code]
Makes the playership accelerate by 10%c in the direction it's facing.
Comment:
you can stop a space object with objmoveto. Then you can set the velocity to anything you want.
Name:
objIsAbandoned
Syntax:
(objIsAbandoned spaceObject)
Argument List:
spaceObject: The space object you want to see if it is abandoned.
Returns:
condition: True if the space object is abandoned. Nil otherwise.
Category:
condition query, spaceobject
Description:
Checks to see if the space object is abandoned. (ie has been destroyed)
Example:
[code](objIsAbandoned gplayership)[/code]
Returns Nil. No time will the player ship be abandoned until the game is over.
[code](objIsAbandoned Nil)[/code]
returns True--useful when a station has been destroyed (from 0.99)
Comment:
Basic conditional query for space objects.
Name:
objIsAngryAt
Syntax:
(objIsAngryAt obj targetObj) -> True/Nil
Argument List:
obj: a desired spaceobject
targetObj: the spaceobject you want to check obj's angriness at
Returns:
Boolean: true/nil depending upon if the target object is angry or not
Category:
spaceobject
Description:
used once, in the &CSCTaskForce;
Example:
[code]
; If we're in the middle of the fleetDelivery mission and we can't
; dock with the target, then we fail
(if (and (eq missionID 'mission1b)
(eq missionStatus 'inprogress)
(objIsAngryAt (objGetObjRefData gSource "Target") gPlayerShip))
(block Nil
(setq missionStatus "failure")
(objSetData gSource "MissionStatus" missionStatus)
(typIncGlobalData &scCSCTaskForce; "missionsFailed")
(shpCancelOrders gPlayerShip)
)
)
[/code]
Comment:
Name:
objIsDeviceEnabled
Syntax:
(objIsDeviceEnabled obj deviceItem) -> True/Nil
Argument List:
obj: the spaceobject that has the deviceItem
deviceItem: the item in question
Returns:
Boolean: true/nil depending if the device is enabled or not
Category:
spaceobject, item
Description:
Not used in Transcendence.tdb
Example:
Comment:
Name:
objIsDeviceSlotAvailable
Syntax:
(objIsDeviceSlotAvailable spaceObject)
Argument List:
spaceObject: The space object you want to see if it has a device slot available.
Returns:
condition: True if the space object has a device slot available. Nil otherwise.
Category:
spaceobject, condition query
Description:
Returns if the space object has a device slot available.
Example:
[code](objIsDeviceSlotAvailable gplayership)[/code]
Returns if the player ship have a device slot available.
Comment:
Basic conditional query for space objects. Device slots are only used for the player ship currently.
Name:
objIsDockedAt
Syntax:
(objIsDockedAt spaceObject spaceObject)
Argument List:
spaceObject: the spaceObject of a ship.
spaceObject: the spaceObject of a station.
Returns:
condition: True if the first space object is docked with the station. Nil otherwise.
Category:
spaceobject, condition query, station
Description:
The function returns true if the spaceObject (ship) is docked to the second spaceObject (station).
Example:
Comment:
Very useful function, that can be used to probe if a ship is docked or not.
It's a complementary function with staGetDockedShips.
Name:
objIsIdentified
Syntax:
(objIsIdentified obj) -> True/Nil
Argument List:
obj: the space object in question
Returns:
Boolean: True/nil depending if it is identified
Category:
spaceobject
Description:
Not used in Transcendence.tdb
Example:
Comment:
Name:
objIsKnown
Syntax:
(objIsKnown obj) -> True/Nil
Argument List:
obj: The spaceObject that you want to test.
Returns:
boolean: True if the space object is known, otherwise Nil.
Category:
condition query, spaceobject
Description:
Query function asking if the spaceObject is known, the object can be known by objSetKnown, seeing it onscreen, or targeting it.
Example:
[code](objIsKnown gSource)[/code]
Returns true if the player has already discovered this space object.
Comment:
Helpful for checking if the player already knows about an object.
Name:
objIsParalyzed
Syntax:
(objIsParalyzed obj)
Argument List:
obj: the spaceobject to check for paralysis
Returns:
boolean: true or nil depending on the spaceobject being paralyzed (EMP'd)
Category:
spaceobject
Description:
Pretty straightforward. Used by the Transpace Jumpdrive.
Example:
Comment:
Name:
objIsRadioactive
Syntax:
(objIsRadioactive obj) -> True/Nil
Argument List:
obj: The obj you want to check for radiation
Returns:
True/Nil depending on the objects radiation state
Category:
radiation, spaceobject, 1.04
Description:
Replaces shpIsRadioactive
Example:
Comment:
Name:
objIsShip
Syntax:
(objIsShip spaceObject)
Argument List:
spaceObject: The space object you want to see if it is a ship.
Returns:
condition: True if the space object is a ship. Nil otherwise.
Category:
spaceobject, condition query
Description:
Returns if the space object is a ship.
Example:
[code](objIsShip gplayership)[/code]
Returns True. (the player's ship is a ship)
Comment:
Basic conditional query for space objects.
Name:
objIsUnderAttack
Syntax:
(objIsUnderAttack spaceObject)
Argument List:
spaceObject: The space object you want to see if it is under attack.
Returns:
condition: True if the space object is under attack. Nil otherwise.
Category:
spaceobject, condition query
Description:
Returns if the space object is under attack or not.
Example:
[code](objIsUnderAttack gplayership)[/code]
Returns weather or not the player ship is under attack.
Comment:
Basic conditional query for space objects.
Name:
objJumpTo
Syntax:
(objJumpTo spaceObject vector)
Argument List:
spaceObject: The space object you want to move.
vector: Where you want to move the space object to.
Returns:
condition: True if successful.
Category:
spaceobject
Description:
Moves the space object to the vector position with a gating animation.
Example:
[code](objJumpTo gplayership (sysVectorPolarOffset gplayership (shpGetDirection gplayership) 500))[/code]
Moves the player ship 500 forward with an gating animation.
Comment:
Basically the same as objMoveTo except it has an extra gating animation.
Name:
objLowerShields
Syntax:
(objLowerShields spaceObject)
Argument List:
spaceObject: The space object you want to disable the shields.
Returns:
condition: True if successful.
Category:
shield, spaceobject
Description:
Disables the shields of the space object.
Example:
[code](objLowerShields gplayership)[/code]
Disables the player ships shields.
Comment:
Not as useful as it could be due to you can't enable shields from in code but still can be fun in disabling the players shield.
Name:
objMakeParalyzed
Syntax:
(objMakeParalyzed spaceObject number)
Argument List:
spaceObject: The space object you want to paralyze.
number: How many ticks you want the space object to be paralyzed.
Returns:
condition: True if successful.
Category:
spaceobject, repair/damage
Description:
Paralyzes a given space object for a given time.
Example:
[code](objMakeParalyzed gplayership 100)[/code]
Paralyzes the player ship for one hundred ticks.
Comment:
Useful as a punishment or a alternative weapon.
Name:
objMatches
Syntax:
(objMatches obj source filter) -> True/Nil
Argument List:
obj: object to check against criteria
source: object to use as source in criteria
filter: criteria to match against
Returns:
Boolean: True or nil depending upon if the spaceobject matches
Category:
spaceobject
Description:
Used to check if an spaceobject matches with the criteria.
The source object is the one used as the base of the criteria
Example:
[code](objMatches (objGetTarget gPlayerShip) (objGetTarget gPlayerShip) "sE")[/code]
checks if the current target of the playership is a ship and an enemy (note, there are easier ways of doing this)
Comment:
For a list of criteria see the wiki:
http://wiki.neurohack.com/transcendence/wiki/functions/legend#object_criteria
Name:
objMoveTo
Syntax:
(objMoveTo spaceObject vector)
Argument List:
spaceObject: The space object you want to move.
vector: Where you want to move the space object to.
Returns:
condition: True if successful.
Category:
spaceobject
Description:
Moves the space object to the vector position.
Example:
[code](objMoveTo gplayership
(sysVectorPolarOffset gplayership (shpGetDirection gplayership) 500))[/code]
Moves the player ship 500 forward.
Comment:
Basically the same as objJumpTo except it doesn't have an extra gating animation.
Name:
objProgramDamage
Syntax:
(objProgramDamage obj hacker progName aiLevel code)
Argument List:
obj: the targeted spaceobject
hacker: the spaceobject doing the hacking
ProgramName: unsure
aiLevel: unsure
code: unsure
Returns:
unsure
Category:
spaceobject
Description:
Not used in Transcendece.tdb.
Example:
Comment:
Name:
objRegisterForEvents
Syntax:
(objRegisterForEvents spaceObject spaceObject)
Argument List:
spaceObject: The space object you want to send the events to.
spaceObject: Where the events are coming from.
Returns:
condition: True if successful.
Category:
spaceobject
Description:
Causes the first space object to receive events generated by second space object.
Example:
Comment:
Used with OnObj events like OnObjDestroyed, OnObjDocked, OnObjJumped, and OnObjEnteredGate.
Name:
objRegisterForSystemEvents
Syntax:
(objRegisterForSystemEvents target range)
Argument List:
target: the targeted spaceobject to register for system events
range: the range within which to listen for system events
Returns:
boolean
Category:
spaceobject, events
Description:
Ths function tells the object to listen to system events in its vicinity (as defined by range). The events are (so far), OnSystemWeaponFire and OnSystemExplosion. They will be called when the respective events happen
Example:
Comment:
used in the battle arena
Name:
objRemoveItem
Syntax:
(objRemoveItem spaceObject itemStruct [number])
Argument List:
spaceObject: The space object you want to remove an item from.
itemStruct: The item you want to remove from the object.
[number]: The optional number of items you want to remove.
Returns:
condition: True if successful.
Category:
spaceobject, item
Description:
Removes the number of items (defaults to whatever is in the itemStruct) from the space object.
Example:
[code](objRemoveItem gPlayerShip (itmCreate &itLongzhuSphere; 1))[/code]
Removes a Longzhu Sphere from the player ship and returns if it could do it.
Comment:
Very useful function for removing used up items or faking a switchable item.
Name:
objRemoveItemEnhancement
Syntax:
(objRemoveItemEnhancement obj item enhancementID)
Argument List:
obj: the spaceobject that has the item enhancement
item: the item that has the enhancement
enhancementID: the id of the enhancement to remove
Returns:
unsure. True/nil depending on success
Category:
spaceobject
Description:
Remove an enhancement previously added to an item on the object.
Example:
Comment:
Name:
objRemoveOverlay
Syntax:
(objRemoveOverlay sObj overlayID)
Argument List:
sObj: spaceOjbect the overlay is on
overlayID: the overlay to remove
Returns:
nothing?
Category:
overlay
Description:
Removes an overlay from a spaceobject.
Example:
From MiscItems.xml
[code]
; Create a barrel of waste every 90 cycles (45 seconds)
(if (geq (objIncOverlayData gSource aOverlayID "counter") 90)
(block (left)
(setq left (objIncOverlayData gSource aOverlayID "wasteCount" -1))
(objAddItem gSource (itmCreate &itRadioactiveWaste; 1))
(objSetOverlayData gSource aOverlayID "counter" 0)
(plyMessage gPlayer "Uranium rod consumed")
(if (eq left 0)
(objRemoveOverlay gSource aOverlayID)
)
)
)
[/code]
Comment:
The only way to remove an overlay that dosen't have a set duration.
Name:
objRepairArmor
Syntax:
(objRepairArmor spaceObject number [number])
Argument List:
spaceObject: The space object you want to repair some armor of.
number: Where on the space object you want to repair the armor on.
[number]: The optional number of the amount you want to repair. If not given repairs for full.
Returns:
condition: True if successful.
Category:
spaceobject, repair/damage, armor
Description:
Repairs the armor at the given spot for other optionally given amount.
Example:
[code](objRepairArmor gPlayerShip 0)[/code]
Repairs the forward armor fully.
Comment:
Would love an armor equipping function that acts just like this one. It is nice and simple and fully able to be done within the code.
Name:
objResume
Syntax:
(objResume obj [gateObj])
Argument List:
obj: the spaceobject to resume
[gateObj]: the spaceobject that is used as a resume point, such as a gate
Returns:
unsure
Category:
spaceobject
Description:
Counterpart to ObjSuspend.
Example:
Taken from &stRogueBaseRescue;
[code]
; Ship appears out of the CSC
(objResume theShip theCSC)
[/code]
Comment:
Name:
objSendMessage
Syntax:
(objSendMessage targetObject sourceObject message) -> True/Nil
Argument List:
targetObject: The spaceObject you want to send the message to.
sourceObject: The spaceObject you want to send the message from.
message: A string containing the message.
Returns:
condition: True if successful.
Category:
message, spaceobject
Description:
Sends a message from a source spaceObject to a target spaceObject. At this point we don't really know what the sourceObject affects.
Example:
[code](objSendMessage gPlayerShip Nil "Success")[/code]
Displays Success if the player is in fight.
Comment:
If you just want to send messages to the player, then use plyMessage instead. One use case for this function is if you are have an item on the playership that is sending messages, and the player switches ships (then he should no longer receive those message).
Name:
objSetData
Syntax:
(objSetData spaceObject string expression)
Argument List:
spaceObject: The space object you want to set data in.
string: The name of the data.
expression: Can be anything except a pointer or a list containing pointers.
Returns:
condition: True if successful.
Category:
data, spaceobject
Description:
Sets the data named by the string to whatever the expression is in the space object.
Example:
[code](objSetData gPlayerShip "rins" 0)[/code]
Sets the rins of the player to 0.
Comment:
Very helpful function in storing data on a space object. Be careful on not storing any objects or pointers or lists containing them.
Name:
objSetDeviceActivationDelay
Syntax:
(objSetDeviceActivationDelay obj deviceItem [delay]) -> True/Nil
Argument List:
obj: the spaceobject that has the item
deviceItem: the item that determines how much power to draw
[delay]: a delay in ticks before consumption
Returns:
Boolean: True or nil depending upon success
Category:
spaceobject, item
Description:
Used to draw power (as if firing a weapon). See comments here: http://wiki.neurohack.com/transcendence/trac/ticket/281
The delay is a one time period to wait before drawing power. The device can be any item, even a virtual item
Example:
[code](objSetDeviceActivationDelay gPlayership (itmCreate 0x0000400D ))[/code]absorb 1MW on the playership
Comment:
Name:
objSetDeviceFireArc
Syntax:
(objSetDeviceFireArc obj deviceItem number number) -> True/Nil
Argument List:
obj: the spaceobject that has the device
deviceItem: the item to set the firearcs of
number: the minFireArc of the item
number: the maxFireArc of the item
Returns:
Boolean: True or nil depending upon success.
Category:
item, spaceobject, 1.06
Description:
New function introduced in 1.06.
Example:
Comment:
objSetDeviceFireArc takes 'omnidirectional as a parameter. This basically places the weapon into an omnidirectional slot.
Name:
objSetDevicePos
Syntax:
(objSetDevicePos obj deviceItem number number) -> True/Nil
Argument List:
obj: the spaceobject that has the device
deviceItem: the device to set the object of
number: angle of the new item's position
number: radius of the new item's position (in pixels)
Returns:
boolean: True or nil depending upon success
Category:
spaceobject, item, 1.06
Description:
New function to set the positions of items on the playership, or ships in general.
Example:
Comment:
Name:
objSetEventHandler
Syntax:
(objSetEventHandler targetObject handlerUNID) -> True/Nil
Argument List:
targetObject: the spaceObject we want to attach the event handler to
handlerUNID: the UNID of the event handler to be attacjed
Returns:
True/Nil depending on success
Category:
spaceobject, event
Description:
Allows one to add arbitrary event handling to any object (ships or stations).
Example:
See &evCommTrafficBehavior; in Vanilla Transcendence for an example
Comment:
Name:
objSetGlobalData
Syntax:
(objSetGlobalData spaceObject string expression)
Argument List:
spaceObject: The space object of the type you want to set data in.
string: The name of the data.
expression: Can be anything except a pointer or a list containing pointers.
Returns:
condition: True if successful.
Category:
spaceobject
Description:
Sets the data named by the string to whatever the expression is in the space object of the type you want it in.
Example:
Comment:
Very helpful function in storing data on a space object of the type you want it in. Be careful on not storing any objects or pointers or lists containing them.
Name:
objSetIdentified
Syntax:
(objSetIdentified obj) -> True/Nil
Argument List:
obj: the spaceobject to set identification of
Returns:
boolean: True/nil depending upon success
Category:
spaceobject
Description:
Used in missions to identify spaceobjects beyond the player's LRS.
Example:
Comment:
Name:
objSetItemCharges
Syntax:
(objSetItemCharges obj item charges [count]) -> itemStruct
Argument List:
obj: the spaceobject that has the item
item: the item to set charges
charges: how many charges you want to set
[count]: the amount of items in the stack to set charges on
Returns:
ItemStruct: the new item
Category:
spaceobject, item
Description:
Used by the NM900 missile pod to reload
Example:
Taken from &itNM900MissilePod;
[code]
; Reloads the pod with missiles
(objSetItemCharges gSource gItem 36)
[/code]
Comment:
Name:
objSetItemData
Syntax:
(objSetItemData obj item attrib data [count]) -> itemStruct
Argument List:
obj: the spaceobject that has the item
item: the item that the data is to go to
attrib: the attribute of the data
data: the actual data
[count]: the amount of items in the stack to set data on. Defaults to all
Returns:
ItemStruct: the new item
Category:
item, spaceobject
Description:
Used to store data on items.
Example:
Taken from stkFreshFoodUpdate
[code]; If the food has turned ripe, mark it
(and (not status) (gr (add (unvGetTick) 1800) expireTime))
(block Nil
(objSetItemData theSource theItem "status" 'ripe (itmGetCount theItem))
(if (eq theSource gPlayerShip)
(plyMessage gPlayer "The "
(itmGetName theItem 0x80) " in your cargo hold look ripe")
)
)
[/code]
Comment:
Name:
objSetKnown
Syntax:
(objSetKnown spaceObject)
Argument List:
spaceObject: The space object that you want have known.
Returns:
condition: True if successful.
Category:
spaceobject
Description:
Sets the space object known.
Example:
[code](objSetKnown gSource)[/code]
Sets the calling space object known.
Comment:
Helpful for making things known in code.
Name:
objSetName
Syntax:
(objSetName spaceObject string)
Argument List:
spaceObject: The space object that you want to rename.
string: The new name.
Returns:
condition: True if successful.
Category:
name, spaceobject
Description:
Renames the space object with whatever the string is.
Example:
[code](objSetName gplayership "Betel")[/code]
Sets the players ship name to Betel.
Comment:
More helpful in changing map labels due to they work on names.
Name:
objSetObjRefData
Syntax:
(objSetObjRefData spaceObject string spaceObject)
Argument List:
spaceObject: The space object that you want store the other space obect in.
string: The name of the space object reference.
spaceObject: The space object that you want to store.
Returns:
condition: True if successful.
Category:
spaceobject
Description:
Stores a space object in a different space object.
Example:
Assuming you want to save the playerships current target on the playership, for later recall:
[code](objSetObjRefData gPlayerShip "CurrentTarget" (objGetTarget gPlayerShip))[/code]
Comment:
Used with objGetObjRefData. Just like objSetData except it can store space objects.
Name:
objSetOverlayData
Syntax:
(objSetOverlayData sObj overlayID attrib data)
Argument List:
sObj: spaceOjbect the overlay is on
overlayID: the overlay to access
attrib: the name of the data attribute to work with
data: arbitrary data to set on overlay
Returns:
nothing?
Category:
overlay
Description:
Sets arbitrary data on an overlay.
Example:
From MiscItems.xml
[code]
; Create a barrel of waste every 90 cycles (45 seconds)
(if (geq (objIncOverlayData gSource aOverlayID "counter") 90)
(block (left)
(setq left (objIncOverlayData gSource aOverlayID "wasteCount" -1))
(objAddItem gSource (itmCreate &itRadioactiveWaste; 1))
(objSetOverlayData gSource aOverlayID "counter" 0)
(plyMessage gPlayer "Uranium rod consumed")
(if (eq left 0)
(objRemoveOverlay gSource aOverlayID)
)
)
)
[/code]
Comment:
Analgous to objSetData.
Name:
objSetOverlayRotation
Syntax:
(objSetOverlayRotation obj overlayID rotation)
Argument List:
obj: the spaceobject that has the overlays
overlayID: a pointer to the live overlay
rotation: the rotation the overlay is to be set
Returns:
unsure
Category:
spaceobject, overlay
Description:
Used to set the angle an overlay is rotated to (around its own axis)
Example:
Comment:
Not used in Transcendence.tdb
Seems like it could be used to make turrets one day.
Name:
objSetPos
Syntax:
(objSetPos spaceObject vector) -> vector
Argument List:
spaceObject: The space object that you want to position.
vector: The position you want to move it to.
Returns:
vector: The spaceObject's vector after it has been moved.
Category:
vector operator, spaceobject
Description:
Moves a space object to the vector given.
Example:
From the Movable Barricade mod.
[code]
(objSetPos gSource
(sysVectorPolarOffset
gplayership
(shpGetDirection gplayership)
5
)
)[/code]
Move gSource (the barricade) 5 light seconds in the direction the player ship is pointing.
Comment:
Name:
objSetShowAsDestination
Syntax:
(objSetShowAsDestination obj [show dist/bearing] [autoclear])
Argument List:
obj: the targeted spaceobject
[show dist/bearing]: whether to show the distance to the destination next to the arrow
[autoclear]: whether to clear the arrow once destination has been reached
Returns:
boolean: true/nil depending on success
Category:
spaceobject
Description:
Makes an arrow point at a certain destination. Optionally it can havedistance and bearing shown as well.
Example:
Comment:
Name:
objSetSovereign
Syntax:
(objSetSovereign spaceObject number)
Argument List:
spaceObject: The space object that you want to change the sovereign of.
number: The UNID of the sovereign you want to set the space objects sovereign to.
Returns:
condition: True if successful.
Category:
ai, spaceobject
Description:
Sets the space object's sovereign to the sovereign referenced by the UNID.
Example:
[code](objSetSovereign gSource &svIndependent;)[/code]
Sets the calling space object's sovereign to svIndependent. (basically friendly independent merchant)
Comment:
Helpful function that allows you to change the Sovereign of the space objects.
Name:
objSetVel
Syntax:
(objSetVel obj velVector)
Argument List:
obj: the spaceobject to change velocity
velVector: the new velocity vector
Returns:
unsure
Category:
vector operator, spaceobject
Description:
Used to change the velocity of the source object. The new velocity must be given as a vector.
Example:
Comment:
Name:
objSuspend
Syntax:
(objSuspend obj)
Argument List:
obj: the spaceobject to be suspended
Returns:
Unsure
Category:
spaceobject
Description:
Used to remove spaceobjects from a system to be returned later on with the objResume function.
Example:
Taken from &stBattleArena;
[code]
(block Nil
(objMoveTo aObjDocked gSource)
(shpCancelOrders aObjDocked)
(objSuspend aObjDocked)
)
[/code]
Comment:
Cannot be a station or a wreck to be suspended.
Name:
objUnregisterForEvents
Syntax:
(objUnregisterForEvents spaceObject spaceObject)
Argument List:
spaceObject: The space object that you want to stop getting messages to.
spaceObject: The space object that you want to stop getting messages from.
Returns:
condition: True if successful.
Category:
spaceobject
Description:
Causes the first space object to stop receiving events generated by second space object.
Example:
Comment:
Stops the events that were caused by objRegisterForEvents.
Name:
objUnregisterForSystemEvents
Syntax:
(objUnregisterForSystemEvents target)
Argument List:
target: the spaceobject to unregister
Returns:
unsure
Category:
spaceobject
Description:
Used to unregister the target from receiving system events.
Used by the battle arena Maximus
Example:
Comment:
Name:
obSetOverlayRotation
Syntax:
(obSetOverlayRotation sObj overlayID rotation)
Argument List:
sObj: spaceOjbect the overlay is on
overlayID: the overlay to access
rotation: desired orientation of overlay
Returns:
nothing?
Category:
overlay
Description:
Setes the current facing of the overlay. For graphical coverlays.
Example:
Comment:
Not used in TranscendenceSource 1.04
Name:
or
Syntax:
(or [condition]^1)
Argument List:
[condition]: Something other than Nil or Nil
^1
Returns:
condition: the result of oring all of the conditions
Category:
logical operator
Description:
Returns True if any the conditions are not Nil otherwise returns Nil.
Example:
[code](block (someCondition)
(setq someCondition True)
(or someCondition Nil)
)[/code]
This will return a True.
Comment:
Logical functions are very important in if and while functions.
Name:
plyChangeShip
Syntax:
(plyChangeShip player newShip) -> True/Nil
Argument List:
player: this will usually be gPlayer
newShip: the space object to transfer to
Returns:
True or Nil depending on the success of the transfer
Category:
spaceobject, ship
Description:
This function allows you to switch the playership. You have to take care of transferring items yourself.
Example:
Comment:
All data set by objSetData is cleared from the target ship. The original player ship's data is moved to the new ship, and the prior player ship's data is also cleared.
Name:
plyCharge
Syntax:
(plyCharge player [currency] number) -> number
Argument List:
player: The player.
[Currency]: the UNID of the currency
number: The number of credits to charge.
Returns:
number: The number of credits left.
Category:
economy, player, cash
Description:
Charges the player the given number of credits and returns how much the player has left.
Example:
[code](plyCharge gplayer 1)[/code]
Charges the player one credit and returns how many credits the player has left.
Comment:
Basic credit manipulation function.
The 1.06 thread
http://neurohack.com/transcendence/forums/viewtopic.php?f=15&t=4292
says to use objCharge instead.
Name:
plyClearShowHelpRefuel
Syntax:
(plyClearShowHelpRefuel player)
Argument List:
player: The player.
Returns:
condition: True if successful.
Category:
help, player
Description:
Stops the help message showing when the players fuel gets low.
Example:
Comment:
It would be nice to be able to turn off the other kinds of help messages like the jump message.
Name:
plyComposeString
Syntax:
(plyComposeString player string v1 v2 ... vn) -> composedString
Argument List:
player: The player.
string: The formatted string.
v1 ... vn: these will replace %1%, %2%, etc. in string in the same manner that the subst function does.
Returns:
composedString: a string with the proper substitutions made for the
Category:
player, string operator
Description:
Takes a string that can include substitution tokens and outputs a string that has appropriate things substituted for those tokens.
(see comment for list of tokens)
Example:
[code](plyComposeString gPlayer (cat "Hey boss! "
"That %man% looks like %Name% %2% by %his% %1%! "
"Should I confront %him%?") "new ship" "standing")[/code]
Will return one of following strings depending on the players gender ( ___ is the player's name):
"Hey boss! That man looks like ___ standing by his new ship! Should I confront him?"
"Hey boss! That woman looks like ___ standing by her new ship! Should I confront her?"
Comment:
KNOWN VALID TOKENS:
Gender Based:
%him% him or her
%sir% sir or ma'am
%his% his or her
%son% son or daughter
%brother% brother or sister
%man% man or woman
Others:
%Name% name of the player
String substitutions (like subst):
%1% %2% %3% %4% ...
%-1% %-2% %-3% %-4% ...
Using %-1% instead of %1%, %-2% instead of %2%, etc. will capitalize the first letter of the strings substituted in.
Name:
plyCredit
Syntax:
(plyCredit player [currency] number) -> number
Argument List:
player: The player.
[Currency]: the UNID of the currency
number: The number of credits to credit.
Returns:
number: The number of credits left.
Category:
cash, player
Description:
Credits the player the given number of credits and returns how much the player has left.
Example:
[code](plyCredit gplayer 1)[/code]
Credits the player one credit and returns how many credits the player has left.
Comment:
Basic credit manipulation function.
The 1.06 thread
http://neurohack.com/transcendence/forums/viewtopic.php?f=15&t=4292
says to use objCredit instead.
Name:
plyDestroyed
Syntax:
(plyDestroyed player string)
Argument List:
player: The player.
string: The ending string.
Returns:
condition: True (I don't really know)
Category:
repair/damage, player
Description:
Ends the game with the string on the last screen.
Example:
[code](plyDestroyed gplayer "ha ha you lose")[/code]
The player loses with an ending screen with ha ha you lose on it.
Comment:
Nice function allowing to end the game without the fighting death.
Name:
plyEnableMessage
Syntax:
(plyEnableMessage player messageID True/Nil) -> True/Nil
Argument List:
player: the player
messageID: the ID of the message
True/Nil: to enable or disable a message
Returns:
boolean: True/nil depending upon success
Category:
message, player
Description:
Used to manipulate the help messages "Press D to Dock."
Example:
Taken from &dsManualRefuel;
[code]
; No need to show help about refueling
(plyEnableMessage gPlayer 'refuelHint Nil)
[/code]
Comment:
There is a list of the current messages on the wiki:
http://wiki.neurohack.com/transcendence/wiki/functions/legend#messages
Name:
plyGetCredits
Syntax:
(plyGetCredits player [currency]) -> number
Argument List:
player: The player.
[Currency]: the UNID of the currency
Returns:
number: The number of credits that the player has.
Category:
player, cash, economy
Description:
Returns the amount of credits the player has.
Example:
[code](plyGetCredits gplayer)[/code]
Returns the amount of credits the player has.
Comment:
Basic credit function for the player, most useful for comparison.
The 1.06 thread
http://neurohack.com/transcendence/forums/viewtopic.php?f=15&t=4292
says to use objGetCredits instead.
Name:
plyGetGenome
Syntax:
(plyGetGenome spaceObject)
Argument List:
spaceObject: works only with gPlayership
Returns:
string: the sex of the player
Category:
0.99, player
Description:
This function returns if the player is male or female depending on what the player choose in the main game screen.
Example:
[code](plyGetGenome spaceObject)[/code]
Returns humanMale or humanFemale
Comment:
Simple function for retrieving data on the player.
Name:
plyGetInsuranceClaims
Syntax:
(plyGetInsuranceClaims player)
Argument List:
player: The player.
Returns:
number: The number of insurance claims the player has had.
Category:
deprecated
Description:
Returns the amount of insurance claims the player has had.
Example:
[code](plyGetInsuranceClaims gplayer)[/code]
Returns the amount of insurance claims the player has had.
Comment:
Basic credit function for the player, used to see how much the insurance company should charge.
Dummied out by 1.08b
Name:
plyGetItemStat
Syntax:
(plyGetItemStat player stat criteria) -> value
Argument List:
player: the player identifier (always gPlayer currently)
stat: name of statistic
criteria: criteria of any sort
Returns:
value: what the stat is
Category:
player
Description:
Used to get conduct stats and such.
Example:
taken from intGetGlobalAchievements
[code]
; Commerce stats
(setq totalGMProfit (subtract (plyGetItemStat gPlayer
"itemsSoldValue" "*~fudam -Fuel; -Illegal; -Lux; -Meds;")
(plyGetItemStat gPlayer
"itemsBoughtValue" "*~fudam -Fuel; -Illegal; -Lux; -Meds;"))
)
(setq totalArmsProfit (subtract (plyGetItemStat gPlayer
"itemsSoldValue" "wsam")
(plyGetItemStat gPlayer "itemsBoughtValue" "wsam"))
)
(setq totalEquipProfit (subtract (plyGetItemStat gPlayer
"itemsSoldValue" "fud~ws")
(plyGetItemStat gPlayer "itemsBoughtValue" "fud~ws"))
)
(setq totalMedsProfit (subtract (plyGetItemStat gPlayer
"itemsSoldValue" "*~wsam +Meds")
(plyGetItemStat gPlayer "itemsBoughtValue" "*~wsam +Meds"))
)
(setq totalLuxProfit (subtract (plyGetItemStat gPlayer
"itemsSoldValue" "*~wsam +Lux")
(plyGetItemStat gPlayer "itemsBoughtValue" "*~wsam +Lux"))
)
(setq totalIllegalProfit (subtract (plyGetItemStat gPlayer
"itemsSoldValue" "*~wsam +Illegal")
(plyGetItemStat gPlayer "itemsBoughtValue" "*~wsam +Illegal"))
)
[/code]
Comment:
Name:
plyGetRedirectMessage
Syntax:
(plyGetRedirectMessage player)
Argument List:
player: The player.
Returns:
string: The stored redirected messages.
Category:
player, message
Description:
Returns the stored redirect messages. When a message is stored it is concatenated onto the redirect string.
Example:
[code](block Nil
(plyRedirectMessage gplayer True)
(plyMessage gplayer "This string will be stored for later use")
(plyMessage gplayer "cat example.")
(plyGetRedirectMessage gplayer)
)[/code]
Returns the string "This string will be stored for later usecat example.".
Comment:
Interesting function that is helpful in storing messages for later display like when you are in a dockscreen.
Name:
plyGetStat
Syntax:
(plyGetStat player stat) -> value
Argument List:
player: the player
stat: the game statistic
Returns:
value: the value of the statistic
Category:
player
Description:
Used to get statistics.
Example:
Taken from intGetGlobalAchievements
[code]
; Conducts
(setq systemData (plyGetStat gPlayer "systemData"))
(setq neverBacktracked
(not (filter systemData theData
(not (eq (item theData 1) (item theData 2))))))
(setq friendlyShipsDestroyed (plyGetStat gPlayer
"friendlyShipsDestroyed"))
(setq friendlyStationsDestroyed (plyGetStat gPlayer
"friendlyStationsDestroyed"))
[/code]
Comment:
Name:
plyIncreaseDominaRel_deprecated
Syntax:
(plyIncreaseDominaRel_deprecated player number)
Argument List:
player: The player.
number: The amount you want to raise your domina relationship by number.
Returns:
condition: True
Category:
player, 0.98
Description:
Increases the players domina relationship.
Example:
[code](plyIncreaseDominaRel gplayer 20)[/code]
Increases the players relationship with Domina.
Comment:
Basic player function. Will be more useful once there are more powers.
Function deprecated in 0.99
Name:
plyIncreaseOracusRel_deprecated
Syntax:
(plyIncreaseOracusRel_deprecated player number)
Argument List:
player: The player.
number: The amount you want to raise your Oracus relationship by number.
Returns:
condition: True
Category:
player, 0.98
Description:
Increases the players Oracus relationship.
Example:
[code](plyIncreaseOracusRel gplayer 20)[/code]
Increases the players relationship with Oracus.
Comment:
Basic player function. Currently there are no Oracus powers implemented ingame. (v. 0.98d)
Function deprecated in 0.99
Name:
plyInsure
Syntax:
(plyInsure player)
Argument List:
player: The player.
Returns:
condition: True
Category:
deprecated
Description:
Insures the players ship.
Example:
[code](plyInsure gplayer)[/code]
Insures the players ship.
Comment:
Basic player function.
Dummied out by 1.08b
Name:
plyIsInsured
Syntax:
(plyIsInsured player)
Argument List:
player: The player.
Returns:
condition: True if the player is insured, Nil otherwise.
Category:
deprecated
Description:
Returns wether or not the player is insured.
Example:
[code](plyIsInsured gplayer)[/code]
Returns whether or not the player is insured.
Comment:
Basic player function.
Dummied out by 1.08b
Name:
plyMessage
Syntax:
(plyMessage player string)
Argument List:
player: The player.
string: The message string.
Returns:
condition: True
Category:
player, message
Description:
Attempts to message the player. If the RedirectMessage is set then cat onto the stored messages.
Example:
[code](plyMessage gplayer "Success")[/code]
Displays Success if the RedirectMessage isn't set.
Comment:
Basic player function. Allowing you to display messages in flight.
Name:
plyRecordBuyItem
Syntax:
(plyRecordBuyItem player item [currency] totalPrice)
Argument List:
player: the player. Usually gPlayer.
item: the item being bought
[currency]: the currency the purchase was in
totalPrice: how much the item was bought for
Returns:
unsure
Category:
player, economy
Description:
How the game keeps track of all the purchases made by the player. Is usually called through the buy dockscreen.
Example:
Taken from &dsRingerRefuel;
[code]
(block (itemsToUse)
(setq itemsToUse (itmCreate (itmGetType gItem) count))
(shpRefuelFromItem gPlayerShip itemsToUse)
(objIncData gPlayerShip "rins" (subtract 0 (multiply count gCost)))
(plyRecordBuyItem gPlayer itemsToUse (multiply count gCost 5))
(scrShowScreen gScreen gPrevScreen gPrevPane)
)
[/code]
Comment:
This is used to display stats
Name:
plyRecordSellItem
Syntax:
(plyRecordSellItem player item [currency] totalPrice)
Argument List:
player: the player. Usually gPlayer.
item: the item sold.
[currency]: the currency the item is sold in
totalPrice: the price of the sold item
Returns:
unsure
Category:
economy, player
Description:
Used to record what the player sells. Usually used in a dockscreen.
Example:
Taken from &dsRingerSell;
[code]
(block (itemsToSell)
(setq itemsToSell (scrRemoveItem gScreen 1))
(objAddItem gSource itemsToSell)
(objIncData gPlayerShip "rins" gCost)
(plyRecordSellItem gPlayer itemsToSell (multiply gCost 5))
(scrShowPane gScreen "Default")
)
[/code]
Comment:
This is used to display stats
Name:
plyRedirectMessage
Syntax:
(plyRedirectMessage player condition)
Argument List:
player: The player.
condition: If Nil makes any future plyMessages display during flight, otherwise sets the redirect message to "" and makes any future plyMessages cat onto the redirect message.
Returns:
condition: True
Category:
player, message
Description:
Controls the activity of plyMessage and if the condition is true clears the stored redirect messages.
Example:
[code](block Nil
(plyRedirectMessage gplayer True)
(plyMessage gplayer "This string will be stored for later use")
(plyMessage gplayer "cat example.")
(plyGetRedirectMessage gplayer)
)[/code]Returns the string "This string will be stored for later usecat example.".
Comment:
Interesting function that is helpful in storing messages for later display like when you are in a dockscreen.
Name:
power
Syntax:
(power base exponent)
Argument List:
base: x in x^y
exponent: y in x^y
Returns:
number: base raised to the exponent power: base^exponent
Category:
math, 0.99
Description:
Returns the the first argument raised to the second argument.
Example:
In the debug console:
[code](power 5 2)
25[/code]
Comment:
If exponent is a negative number, the result will always be zero, as they produce fractions and there is no floating point support.
There is presently a bug wherein raising something to the 0th power returns zero instead of one; see: http://wiki.neurohack.com/transcendence/trac/ticket/537
Name:
random
Syntax:
(random expression [number])
Argument List:
expression : A list or number.
number: The number you want to a random number between them the second must be greater than the first number.
Returns:
expression: If the expression argument is a list it returns a random element of the list, if the expression is a number then returns a number between the expression number and optional number.
Category:
random
Description:
If the expression argument is a list it returns a random element of the list, if the expression is a number then returns a number between the expression number and optional number.
Example:
[code](random 1 10)[/code]
Can return any number between 1 and 10 like 3.
[code](random '(a b c d))[/code]
Can return any element in the list '(a b c d).
Comment:
Very useful function for making variation in code.
Name:
randomTable
Syntax:
(randomTable chance1 exp1 chance2 exp2 ... chancen expn) -> exp
Argument List:
chance1: the chance for the proceeding expression to occur
exp1: the expression to occur if chance1 is chosen
chance2: the chance for the proceeding expression 2 to occur
exp2: the expression to occur if chance2 is chosen
chanceN: the chance for the proceeding expression N to occur
expN: the expression to occur if chanceN is chosen
Returns:
the chosen expression
Category:
random
Description:
A way to simulate the table functionality in transcendence xml. It is basically a shorter way of selecting a random expression.
Example:
The following will have a 10% chance of selecting "1-10", a 20% chance of selecting "11-30", a 30% chance of selecting "31-60" and a 40% chance of selecting "61-100"
[code](randomTable 10 "1-10" 20 "11-30" 30 "31-60" 40 "61-100")[/code]
Comment:
The sum of the chances must equal 100.
Name:
resCreateImageDesc
Syntax:
(resCreateImageDesc imageUNID x y width height) -> imageDesc
Argument List:
imageUNID: the unid of the image
x: the x coordinate of where the image should be
y: the y coordinate of where the image should be
width: the width of the image
height: the height of the image
Returns:
imageDesc: a list of 5 numbers. they are:
the first is the UNID of the image resource as a number,
the second and the third are the x,y coordinates in pixels of the resource image
(from the top left corner of the image)
the fourth and fifth are the sizes of the resource image in pixels.
(first width then height)
Category:
canvas, screen
Description:
used to create an imagedescription in code.
Example:
taken from &itMRADExperiment;
[code]
(resCreateImageDesc &rsMRADConsole; 0 (if MRADProbe1 0 172) 182 172)
[/code]
Comment:
Name:
rollDice
Syntax:
(rollDice die sides [bonus]) -> integer
Argument List:
die: The amount of dice you want to roll
sides: The amount of sides the dice have
[bonus]: A bonus that is applied at the end (can be negative)
Returns:
integer: A number made from "rolling" that many dice and adding them together then applying the bonus.
Category:
random
Description:
Returns a number made from "rolling" that many dice and adding them together then applying the bonus.
Example:
[code](rollDice 1 6 10)[/code]
Returns a number between 11 and 16.
Comment:
Very useful function for making variation in code.
Name:
scrAddAction
Syntax:
(scrAddAction screen actionID pos label [key] [special] code)
Argument List:
screen: dockscreen to work on, usually gScreen
actionID: string to identify action with later
pos: number of action to insert this action before
label: string display text of action
[key]: string shortcut key
[special]: list or token describing special functionality
code: code to execute when player selects action
Returns:
nothing?
Category:
screen, 1.04
Description:
Allows dynamic creation of dockscreen actions from code.
Example:
[code]
; aScreenUNID is the UNID of the screen being shown
; aScreen is the screen name (if this is a local screen)
; aPane is the pane being shown
; shipStatusScreen is the current playership's dockscreen
(if (and
(eq aScreen (objGetDataField gPlayerShip "shipStatusScreen"))
(eq aPane "Default"))
(scrAddAction
gScreen
'myNewAction
3
"Do something cool"
"d"
'default
(scrShowScreen gScreen "&scMyCoolScreen;")
)
)
[/code]
Comment:
Meant for use in , can also be used to make dynamic dockscreens.
Special actions are 'cancel , 'default , 'nextKey , 'prevKey , or a list of these tokens.
"pos" can be -1 to insert as last action on screen.
Implementation discussion available here http://neurohack.com/transcendence/forums/viewtopic.php?t=3537 -- example was adapted from there.
Name:
scrEnableAction
Syntax:
(scrEnableAction screen action enabled) -> success
Argument List:
screen: The screen where you want to enable or disable an action.
action: The string action ID or number (zero is top) of the action.
enabled: If Nil disables the action otherwise enables the action.
Returns:
success: True if successful.
Category:
screen
Description:
Enables or disables actions on the screen. A disabled action looks grayed out and can not be selected.
Example:
[code](scrEnableAction gScreen 0 Nil)[/code]
Disables the top action on the calling screen.
[code](scrEnableAction gscreen 'myNewAction true)[/code]
Enables the action from the scrAddAction example.
Comment:
Basic screen function that allows you to control what the player can and can not select.
Acility to use a string action ID added in 1.04.
Name:
scrExitDock
Syntax:
(scrExitDock screen)
Argument List:
screen: The screen you want to exit after this code.
Returns:
condition: True if successful.
Category:
screen, deprecated
Description:
Returns the player to normal fight after this function is done.
Example:
[code](scrExitDock gScreen)[/code]
Exits the current screen and returns to normal flight.
Comment:
DEPRECATED in 1.04: Use scrExitScreen instead.
Basic screen function that allows you to say when you are done with the screen and want to go back to the normal game.
From George: it makes the player go to normal flight, but functions after (scrExitDock) are still executed (although I have not tried it out).
Name:
scrExitScreen
Syntax:
(scrExitScreen screen ['forceUndock])
Argument List:
screen: Screen to exit, probably always gScreen
['forceUndock]: optinal token, if present will return the player to the game screen instead of the prior dockscreen.
Returns:
nothing?
Category:
screen, 1.04
Description:
Exits the current dockscreen, or the entire dockscreen stack.
Example:
[code]
(scrExitScreen gScreen)
(scrExitScreen gScreen 'forceUndock)
[/code]
The only two invocations of this function in TranscendenceSource, perhaps the only meaningful ones possible.
Comment:
Added in 1.04 to rpelace scrEexitDock.
Name:
scrGetCounter
Syntax:
(scrGetCounter screen)
Argument List:
screen: The screen you want to get the counter from.
Returns:
number: The currently displayed counters value.
Category:
screen, input
Description:
Returns what the counter is currently displaying.
Example:
Comment:
Allows you to get a number inputted by the player.
Name:
scrGetInputText
Syntax:
(scrGetInputText screen)
Argument List:
screen: The screen you want to get the input text from.
Returns:
string: The currently inputted text.
Category:
screen, input
Description:
Returns what the text the player inputted.
Example:
Comment:
Allows you to get a string inputted by the player.
Name:
scrGetItem
Syntax:
(scrGetItem screen)
Argument List:
screen: The screen you want to get the currently selected item from.
Returns:
itemStruct: The currently selected item.
Category:
screen, input
Description:
Returns the currently selected item.
Example:
Comment:
Allows you to get an item selected by the player or the currently selected item by the Initialize element. The Initialize element iterates over every item before they are displayed to the player allowing you to make descriptions, adjust prices, or anything you would need to do for it to display quickly.
Name:
scrGetItemListCursor_deprecated
Syntax:
(scrGetItemListCursor_deprecated screen)
Argument List:
screen: The screen you want to get the currently selected cursor from.
Returns:
itemListCursor: The currently selected cursor.
Category:
screen, input, 0.98, deprecated
Description:
Returns the pointer to where in the list that is being currently selected.
Example:
Comment:
Old function used mostly by old functions. Can not be saved. Use scrGetItem or scrGetListEntry whenever possible.
Function deprecated in 0.99
Name:
scrGetListEntry
Syntax:
(scrGetListEntry screen)
Argument List:
screen: The screen you want to get the currently selected list item from.
Returns:
listitem: the currently selected list item
Category:
input, screen
Description:
This function returns the currently selected list item from a screen.
Example:
[code]
(and (scrGetListEntry gScreen) (geq (plyGetCredits gPlayer) 100))[/code]
Returns True if an entry is selected on gScreen and the player has more than 100 credits.
Comment:
Name:
scrIsFirstOnInit
Syntax:
(scrIsFirstOnInit screen)
Argument List:
screen: The screen you want to see if it is the first screen the player sees.
Returns:
condition: True if the screen is the first one the player sees.
Category:
screen
Description:
Returns if the screen is the first screen the player sees.
Example:
Comment:
I am not quite sure of the cases for this one. Anyone want to investigate?
Name:
scrRefreshItemListCursor_deprecated
Syntax:
(scrRefreshItemListCursor_deprecated)
Argument List:
-
Returns:
-
Category:
0.98, screen
Description:
-
Example:
-
Comment:
Function deprecated in 0.99
Name:
scrRemoveitem
Syntax:
(scrRemoveitem screen number)
Argument List:
screen: The screen you want to remove the item from.
number: How many of the item you want to remove.
Returns:
itemStruct: The removed items.
Category:
screen
Description:
Removes and returns the number of the currently selected items from the screen and whatever is using that screen. (the player ship in every case I can think of)
Example:
Comment:
Very useful in screens where you can "use" up items like buying or looting.
Name:
scrSetActionLabel
Syntax:
(scrSetActionLabel screen action label [key] [special])
Argument List:
screen: The screen you want to change the action text on.
action: The string ID of the action, or it's position starting at 0.
label: string, what you want to change the text to.
[key]: string, define which keystroke will trigger the action.
[special]: list or token, special flags for this action
Returns:
condition: True is successful.
Category:
screen
Description:
Changes the given actions text to the string.
Example:
[code]
(scrSetActionLabel
gScreen
'myNewAction
"Do something extra cool"
"e"
(list 'default 'nextKey)
)
[/code]
Assumes action from scrAddAction example.
Comment:
Allows you to dynamically change the action labels.
Special actions are 'cancel , 'default , 'nextKey , 'prevKey , or a list of these tokens.
Special and the ability to use action id strings added in 1.04.
Name:
scrSetCounter
Syntax:
(scrSetCounter screen number)
Argument List:
screen: The screen you want to set the counter on.
number: The number you want to set the counter too.
Returns:
condition: True is successful.
Category:
input, screen
Description:
Sets the counter on the screen to the given number.
Example:
Comment:
Allows you to set a counter. Useful in making sure the counter has limits or setting an initial value.
Name:
scrSetDesc
Syntax:
(scrSetDesc screen string)
Argument List:
screen: The screen you want to set the description on.
string: The string you want to set the description too.
Returns:
condition: True is successful.
Category:
screen
Description:
Sets the description text of the screen to the given string.
Example:
Comment:
Basic screen function. Will most likely be used on any screen due to it being the only way of displaying general text.
Name:
scrSetDisplayText
Syntax:
(scrSetDisplayText screen ID text [text...])
Argument List:
screen: the screen to display the text
ID: the ID of the text element in the display section to write to
text: the text
[Text...]: more text to display (can be repeated
Returns:
unsure
Category:
screen
Description:
Used to modify what dockscreens say.
Example:
taken from &dsUseDataRom;
[code]
(scrSetDisplayText gScreen "text" theText)
[/code]
Comment:
Name:
scrSetInputText
Syntax:
(scrSetInputText screen string)
Argument List:
screen: The screen you want to set the input text on.
string: The string you want to set the input text too.
Returns:
condition: True is successful.
Category:
screen
Description:
Sets the input text on the screen to the given string.
Example:
Comment:
Useful in having an initial string for text input. Not used in the current xmls.
Name:
scrSetListFilter
Syntax:
(scrSetListFilter screen criteria)
Argument List:
screen: The screen you want to filter the items on.
criteria: The criteria string you want to filter the item list with.
Returns:
condition: True is successful.
Category:
screen
Description:
Sets the list filter from the given screen. Will only display the items that fit the criteria.
Example:
[code](scrSetListFilter gScreen "*U")[/code]
The current screen lists all the non equipped items.
Comment:
Very helpful in filtering item selection screens like loot screens.
Name:
scrShowAction
Syntax:
(scrShowAction screen actionID shown)
Argument List:
screen: the screen to call the function in (always gScreen)
actionID: the ID or position of the action to modify
shown: whether to show the action or not
Returns:
unsure
Category:
screen
Description:
Used to show or hide an action. The ID can be either a label (when the action is added using scrAddAction) or a position (counted from 0), when the action is added through xml.
`shown` is an expression that must evaluate to either true or nil. If it is nil, then the action will not be displayed and not be selectable.
Used by the container habitats to modify what questions you can ask them.
Example:
taken from &dsContainerHabitatReward;
[code]
; Equipment location available after 5 donation points
(scrShowAction gScreen 0 (geq donationPoints 5)
[/code]
Comment:
Name:
scrShowPane
Syntax:
(scrShowPane screen string)
Argument List:
screen: The current screen.
string: The name of the pane you want to navigate to.
Returns:
condition: True is successful.
Category:
screen
Description:
Navigates to the named pane.
Example:
[code](scrShowPane gScreen "GoodLuck")[/code]
Navigates to the pane named GoodLuck.
Comment:
Basic screen function allowing you to go between panes.
Name:
scrShowScreen
Syntax:
(scrShowScreen screen string [string])
Argument List:
screen: The current screen.
string: The name of the screen you want to navigate to.
[string]: which pane to display from the screen.
Returns:
condition: True is successful.
Category:
screen
Description:
Navigates to the named screen.
Example:
[code](scrShowScreen gScreen "Introduction")[/code]
Navigates to the screen named Introduction.
[code](scrShowScreen gScreen &dsRPGLoot;)[/code]
Is another example.
Comment:
Basic screen function allowing you to go between screens.
Name:
seededRandom
Syntax:
(seededRandom number expression [number])
Argument List:
number: the seed of the random number generator
expression: can be a number or a list.
[number]: The number you want to a random number between them the second must be greater than the first number.
Returns:
expression: If the expression argument is a list it returns a random element of the list, if the expression is a number then returns a number between the expression number and optional number.
Category:
random, 0.99
Description:
If the expression argument is a list it returns a random element of the list depending on the seed, if the expression is a number then returns a number between the expression number and optional number, always depending on the seed.
Example:
[code](seededRandom 1 1 10)[/code]
Returns 2
[code](seededRandom 1 '(a b c d e f g h i l))[/code]
Returns b
Comment:
Very useful function for making variation in code. If necessary the seed can be randomized using sysTicks (old BASIC trick)
Name:
set
Syntax:
(set string expression)
Argument List:
string: The name of the variable you want to set.
expression: The thing you want to store in the variable.
Returns:
expression: Whatever the expression is.
Category:
store
Description:
Stores the expression in the variable named by the string.
Example:
[code](set "notFound" True)[/code]
Stores True in the variable notfound.
Comment:
Not used in the xml due to setq being faster. Only needed if you want to mess with the variable names.
Name:
setq
Syntax:
(setq variable expression)
Argument List:
variable: The variable you want to set.
expression: The thing you want to store in the variable.
Returns:
expression: Whatever the expression is.
Category:
store
Description:
Stores the expression in the variable.
Example:
[code](setq notFound True)[/code]
Stores True in the variable notfound.
Comment:
Used over 3k times in the xml. Even the trivial code uses this.
Name:
shpAddEnergyField
Syntax:
(shpAddEnergyField ship number number)
Argument List:
ship: The ship that is using the energy field.
number: The UNID of the energy field.
number: How long in ticks the energy field will last.
Returns:
condition: True is successful.
Category:
ship, deprecated
Description:
Puts the given energy field on the given ship for the given amount of time.
Example:
[code](shpAddEnergyField gplayership &sfStrengthen; 600)[/code]
Puts the strengthen energy field on the player ship for 600 ticks.
Comment:
DEPRECATED: Use ObjAddOverlay instead.
Interesting function. Would be more interesting if ShipEnergyFieldType had more attributes.
Name:
shpCancelOrders
Syntax:
(shpCancelOrders ship)
Argument List:
ship: The ship that you want to cancel the orders of.
Returns:
condition: True is successful.
Category:
ship, orders
Description:
Removes any orders the ship currently has.
Example:
[code](shpCancelOrders gPlayerShip)[/code]
Removes any orders for the player ship. Orders for the play ship come in the form of those green arrows.
Comment:
To be done before giving new orders.
Name:
shpCanInstallArmor
Syntax:
(shpCanInstallArmor ship itemStruct)
Argument List:
ship: The ship that you want to see if it can equip the armor.
itemStruct: The armor you want to see if it can be equipped.
Returns:
number: 1 if the armor is to heavy, 0 if it can be installed.
Category:
ship
Description:
Checks to see if the ship can install that armor.
Example:
[code](shpCanInstallArmor gPlayerShip (itmCreate 0x4001 1))[/code]
Returns 0 because all player ships can install light titanium armor.
Comment:
Returns a number instead of a condition to allow for reasons why it can not install the armor.
Name:
shpCanInstallDevice
Syntax:
(shpCanInstallDevice ship itemStruct)
Argument List:
ship: The ship that you want to see if it can equip the device.
itemStruct: The device you want to see if it can be equipped.
Returns:
number: 0 if it can be installed, 2 the ship can not support any more devices, 4 can install will also remove shield, 5 can install will also remove drive, 6 can install will also remove missile launcher, 7 can not reactor not powerful enough, 8 can not install already have a cargo hold, 9 can install will also remove reactor, 10 can not install cargo expansion to large for the ship, 11 can not install creator too powerful, 12 can not install too many weapons, 13 can not install too many non weapons.
Category:
ship
Description:
Checks to see if the ship can install that device.
Example:
Checks to see if the ship can install that device.
Comment:
Returns a number instead of a condition to allow for reasons why it can not install the device.
Name:
shpCanRemoveDevice
Syntax:
(shpCanRemoveDevice ship item) -> installCode
Argument List:
ship: The ship that has the item you want to check installed.
item: The item you want to check.
Returns:
installCode: 1 if removing the device would cause the cargo hold to become too small, 0 if it can be removed. 2 if the item is not installed in the first place.
Category:
ship
Description:
Checks to see if the ship can remove the device.
Example:
Comment:
Returns a number instead of a condition to allow for reasons why it can not remove the device.
Name:
shpConsumeFuel
Syntax:
(shpConsumeFuel ship number)
Argument List:
ship: The ship that you want to remove fuel from.
number: How much fuel you want to remove.
Returns:
number: Fuel remaining.
Category:
ship, fuel
Description:
Removes the given amount of fuel from the ship.
Example:
[code](shpConsumeFuel gplayership 0)[/code]
Returns how much fuel the player has left.
[code](shpConsumeFuel theShip (shpGetFuelLeft (theShip))[/code]
Removes all fuel from the ship.
[code]
(if (gr (shpGetFuelLeft theShip) 502500)
(shpConsumeFuel theShip 500000)
(plyMessage gPlayer "Not enough fuel.")
)
[/code]
Uses one Longzhu Sphere's worth of fuel from the reactor, but won't take the ship below one helium3 rod's worth of fuel.
Comment:
Useful for creating items that cost fuel per use.
Name:
shpDamageArmor
Syntax:
(shpDamageArmor ship number number number)
Argument List:
ship: The ship that you want to damage an armor segment on.
number: Where on the ship the armor segment is.
number: The damage type.
number: The amount of damage.
Returns:
condition: True is successful.
Category:
ship, repair/damage, armor
Description:
Damages the armor with the given damage and damage type.
Example:
[code](shpDamageArmor gplayership 0 0 1)[/code]
Does one point of kinetic damage to the players forward armor.
Comment:
Very nice function for damaging armor in code. Would be nice if you could do this with shields too.
Use 'nosrsflash to stop the Red Screen of Death from showing, as requested in this thread: http://wiki.neurohack.com/transcendence/trac/ticket/648
Name:
shpDamageItem
Syntax:
(shpDamageItem ship itemListCursor)
Argument List:
ship: The ship that you want to damage an item in.
itemListCursor: Where on the ship the item is.
Returns:
condition: True is successful.
Category:
ship, item, repair/damage
Description:
Damages the item pointed to by the itemListCursor.
Example:
Comment:
Damages the item pointed to by the itemListCursor.
Name:
shpDecontaminate
Syntax:
(shpDecontaminate ship)
Argument List:
ship: The ship that you want to decontaminate.
Returns:
condition: True is successful.
Category:
radiation, ship
Description:
Removes any radiation from the given ship.
Example:
[code](shpDecontaminate gplayership)[/code]
Decontaminates the player ship.
Comment:
Limited use but still interesting for a chance type item.
Name:
shpEnhanceItem
Syntax:
(shpEnhanceItem ship itemListCursor [number])
Argument List:
ship: The ship that you want to enhance an item in.
itemListCursor: Where on the ship the item is.
number: The enhance code.
Returns:
condition: True is successful.
Category:
ship, enhancement, item
Description:
Enhances the pointed at item.
Example:
Comment:
* enhanceCodes (always starts with 0x*Value*, e.g. 0x0101):
* 010X For enhancing hitpoint; 10% hp multiplied with X (e.g., 0101 = +10% hp, 0102 = +20% hp, etc.)
* 810X for reducing hitpoints;-10% hp multiplied with X (e.g., 8101 = -10% hp, 8102 = -20% hp, etc.)
* 0200 Regenerate (like Duralloy, only applies to armor)
* 8200 Decay (like Transuranic, only applies to armor)
* 03YX Reflect damage type Y with X effectiveness (X{effectiveness} starts with 0=50% and rises in 5% steps; Y{dam type} is listed further down)
* 83Y0 Transparency to damage Y, applies only to shields (e.g., 8300 = shield does not absorb laser damage, 8310 = shield does not reflect kinetic damage).
* 050X reduce damage to armor/shield (e.g., 0500 = armor/shield takes 100% of damage; 0501 = 90% of damage; 0502 = 80% of damage, etc.)
* 850X enhance damage to armor/shield (e.g., 8500 = armor/shield takes 100% of damage; 8501 = 111% damage; 8502 = 125% damage; 8503 = 143% damage, etc.)
* 060X reduce ENERGY damage (e.g., laser, particle, etc.). % is same as 050X.
* 860X enhance ENERGY damage. % is same as 850X.
* 070X reduce MATTER damage (e.g., kinetic, blast, etc.). % is same as 050X.
* 870X enhance MATTER damage. % is same as 850X.
* 08YX reduce damage when damage is of type Y or of type Y+1. For example, 080X adjusts damage to armor/shield when hit by either laser or kinetic damage. % is same as 050X.
* 88YX enhance damage when damage is of type Y or of type Y+1. % is same as 850X.
* 09YX reduce damage when damage is of type Y (e.g., 0901 = armor/shield takes 90% damage from laser; 0911 = armor/shield takes 90% damage from kinetic). % is same as 050X.
* 89YX enhance damage when damage is of type Y. % is same as 850X.
* 0AYX reduce damage with % same as 050X. If damage is of type Y+2, adjusts damage with % equal to 1.5 times 050X. (e.g., 0A05: For laser damage, adjustment is 50%; for particle damage, adjustment is 75%.)
* 8AYX If damage is of type Y, enhance damage with % same as 050X. If damage is of type Y+2, adjusts damage with % equal to 1.5 times 850X.
* 0B00 Armor is immune to radiation.
* 0B10 Armor is immune to blinding.
* 0B20 Armor is immune to EMP.
* 0B30 Armor is immune to device damage.
* 0B40 Armor is immune to disintegration.
* 0C00 Armor is immune to blinding/EMP/device damage.
* 8C00 Armor interferes with shields (like meteorsteel) - no shields.
* 0D00 Armor regenerates near sun - solar regeneration.
* 0E00 Armor refuels reactor near sun - solar power.
* 0F0X Shield consumes less power (X values: 0=100%, 1=90% etc. of original value).
* 8F0X Shield consumes more power (8F00 = shield consumes 100% of rated power, 8F01 = consumes 111% of rated power, 8F02 = consumes 125% of rated power, 8F03 = consumes 143% of rated power).
* Reducing: changes by 10% -> x/% 0/100 1/90 2/80 3/70 4/60 5/50 6/40 7/30 8/20 9/10 (A/0?)
* Enhancing: changes by ??? -> x/% 0/100 1/111 2/125 3/143 4/ 5/ 6/ 7/ 8/ 9/ (A/)
Name:
shpEnhanceSRS
Syntax:
(shpEnhanceSRS ship)
Argument List:
ship: The ship that you want to enhance the visual display.
Returns:
condition: True is successful.
Category:
enhancement, ship
Description:
Enhances the visual display of the ship.
Example:
[code](shpEnhanceSRS gplayership)[/code]
Enhances the visual display of the player ship.
Comment:
Limited use but still interesting for a chance type item.
Name:
shpFixBlindness
Syntax:
(shpFixBlindness ship [noMessage])
Argument List:
ship: The ship that you want to fix the visual display.
[noMessage]: If True will disable the message that the player gets when the function is used
Returns:
condition: True is successful.
Category:
repair/damage, ship
Description:
Fixes the visual display of the ship.
Example:
[code](shpFixBlindness gplayership true)[/code]
Fixes the visual display of the player ship without the message.
Comment:
Limited use but still interesting for a chance type item.
Name:
shpGetAISetting
Syntax:
(shpGetAISetting ship setting)
Argument List:
ship: the ship to get the AI setting
setting: the setting of the AI
Returns:
unsure
Category:
ship, spaceobject, 1.06
Description:
Used to get the value of a ships AISetting
Example:
Currently not used in the Transcendence.tdb
Comment:
Look at the AISettings section of ships for examples of the values to get and set
Name:
shpGetArmor
Syntax:
(shpGetArmor ship number)
Argument List:
ship: The ship that you want to get the armor from.
number: Where on the ship you want to get the armor from.
Returns:
itemStruct: The item struct of the armor.
Category:
ship, armor
Description:
Returns what armor the ship is equipped with at the given location.
Example:
[code](shpGetArmor gplayership 0)[/code]
Returns an item struct of the forward armor.
Comment:
Useful for testing various things about the ships armor.
Name:
shpGetArmorCount
Syntax:
(shpGetArmorCount ship)
Argument List:
ship: The ship that you want to get how many segments of armor it has.
Returns:
number: The number of segments of armor that the ship has.
Category:
ship, armor
Description:
Returns how many segments of armor the ship has.
Example:
[code](shpGetArmorCount gplayership)[/code]
Returns 4 for the vanilla ships.
Comment:
Useful for fors that iterate over a ships armor.
Name:
shpGetArmorMaxHitPoints
Syntax:
(shpGetArmorMaxHitPoints ship number)
Argument List:
ship: The ship that you want to get what the max hp of the segment of armor is.
number: Where on the ship the armor you want to get the max hp of.
Returns:
number: The max hp of the specified armor.
Category:
ship, armor
Description:
Returns how many hp the given armor of the ship has.
Example:
Comment:
Useful for repairing armor or doing damage proportional to the max hp of the armor.
Name:
shpGetClass
Syntax:
(shpGetClass ship)
Argument List:
ship: The ship that you want to get the UNID of.
Returns:
number: The UNID of the ship.
Category:
ship, unid
Description:
Returns the UNID of the ship.
Example:
Comment:
Useful for seeing what kind of ship you are dealing with and acting accordingly.
Name:
shpGetClassName
Syntax:
(shpGetClassName class flags) -> class name
Argument List:
class: the UNID or spaceobject of the ship
flags: name flag
Returns:
the ships class name
Category:
spaceobject, ship
Description:
Used to get the class name of a ship. The class name of the wolfen for example, is Wolfen-class gunship. It is a mixture of the class and type attributes of the ship.
Example:
Taken from &stKorolovShipping;
[code]
(cat
(objGetName gTransport 4)
" (" (shpGetClassName gTransport 4) ")"
" is transporting " (intRoundUp cargoValue 1000) " credits worth of cargo."
" She will pay " escortFee " credits"
" if you escort her safely to "
(objGetName gDestination 4) "."
"\n\nDo you wish to accept this assignment?"
)
[/code]
Comment:
A list of name flags can be found here:
http://wiki.neurohack.com/transcendence/wiki/modding/function/legend#name_flags
Name:
shpGetDataField
Syntax:
(shpGetDataField number string)
Argument List:
number: the space object or the shipclass UNID of the ship you want data from.
string: the name of the data field of the ship.
Returns:
expression: returns the value or the string of the data field. If there is no value, nothing is returned, not even Nil
Category:
unid, 0.99, ship
Description:
This function retrieves some base data from a ship. It can access some of the values from the ship class's xml, and some other values. (see below).
Example:
[code](shpGetDataField (shpGetClass gPlayership) "score")[/code]
Returns 105 for the Freighter.
[code](shpGetDataField gPlayerShip "level")[/code]
Returns 2 for the Sapphire.
Comment:
An important function that can retrieve some base data about a ship. Specifically the following fields can be retrieved:
cargoSpace
explosion
fireAccuracy
fireRangeAdj
fireRateAdj
launcher
launcherUNID
level
maxSpeed
maneuver
manufacturer
name
primaryArmor
primaryArmorUNID
primaryWeapon
primaryWeaponRange
primaryWeaponRangeAdj
primaryWeaponUNID
score
shield
shieldsUNID
thrustToWeight
There might be more values that can be retrieved, but at the moment those are the ones that are known.
Name:
shpGetDirection
Syntax:
(shpGetDirection ship)
Argument List:
ship: The ship that you want to get the direction of.
Returns:
number: The direction of the ship in degrees.
Category:
ship
Description:
Returns the direction of the ship.
Example:
(objMoveTo gplayership (sysVectorPolarOffset gplayership (shpGetDirection gplayership) 500))
Moves the player ship 500 forward.
Comment:
Useful for objJumpTo and objIncVel.
Name:
shpGetFuelLeft
Syntax:
(shpGetFuelLeft ship)
Argument List:
ship: The ship that you want the remaining fuel of.
Returns:
number: The amount of fuel left.
Category:
reactor, ship
Description:
Returns the amount of fuel in the ship.
Example:
Comment:
The same as shpConsumeFuel with no fuel consumed.
Name:
shpGetFuelNeeded
Syntax:
(shpGetFuelNeeded ship item)
Argument List:
ship: ship whose fuel situation is being considered.
item: item to be used to refuel ship.
Returns:
number: returns the number of that item needed to refuel the ship.
Category:
ship, fuel
Description:
This function returns how many of the item passed to the function are needed to refuel the ship.
Example:
[code]
(setq maxNeeded (shpGetFuelNeeded gPlayerShip thisItem))
[/code]
Used in working out the 'Refuel' messages when refuelling from the cargo while in flight.
Comment:
shpGetFuelNeeded return an exception error if the last parameter is Nil
Name:
shpGetGlobalData_deprecated
Syntax:
(shpGetGlobalData_deprecated number string)
Argument List:
number: The UNID of the ship you want the data from.
string: The name of the data you want.
Returns:
The data named by the string from the ships class. All ship in the same class share the same global data. Returns Nil if there is no data as named by the string.
Category:
data, ship, 0.98
Description:
Returns the data named by the string for the ships class.
Example:
Comment:
Basically the same as objGetGlobalData except you are using an UNID instead of a space object.
DEPRECATED: Use typGetGlobalData instead
Name:
shpGetImageDesc
Syntax:
(shpGetImageDesc spaceObject [number])
Argument List:
spaceObject: the spaceobject that you want the details of the image used.
number: optional parameter that specifies the rotation of the ship.
Returns:
list: a list of 5 numbers, the first is the UNID of the image resource as a number, the second and the third are the x,y coordinates in pixels of the resource image (from the top left corner of the image) the fourth and fifth are the sizes of the resource image in pixels. (first width then
height)
Category:
0.99, ship, unid
Description:
Returns details on the resource image used by a ship.
Example:
[code](shpGetImageDesc gPlayership)[/code]
returns (61757 0 0 64 64) if the player is using the Freighter.
Comment:
Helpful function for image resource management. For retrieving informations on station images use objGetImageDesc
Name:
shpGetItemCharges_deprecated
Syntax:
(shpGetItemCharges_deprecated ship itemStruct)
Argument List:
ship: The ship that the item is in.
itemStruct: The item that you want to see how many charges are on.
Returns:
number: The number of charges on the item.
Category:
0.98, ship, item
Description:
Returns the number of charges on the item.
Example:
Comment:
Don't ask me why this is a ship function. Your guess is as good as mine.
Function deprecated in 0.99, use itmGetCharges instead.
Name:
shpGetItemDeviceName
Syntax:
(shpGetItemDeviceName ship item) -> device name of item (or -1)
Argument List:
ship: the ship that has the item
item: the item that has the needed name
Returns:
the name of the item or -1 if it is not installed
Category:
ship, spaceobject, item
Description:
Used to get weapon names on ships
Example:
taken from &itDamageWeaponROM;
[code]
(if (and notFound
(eq (shpGetItemDeviceName gSource weaponItem) 0))
(block Nil
(shpDamageItem gSource theItem)
(objSendMessage gSource Nil (cat (itmGetName weaponItem 33)
" damaged by defective ROM"))
(setq notFound Nil)
)
)
[/code]
Comment:
Name:
shpGetMaxSpeed
Syntax:
(shpGetMaxSpeed spaceObject)
Argument List:
spaceObject: a ship that you want the max speed from.
Returns:
number: the max speed of the ship.
Category:
ship, 0.99
Description:
This function returns the value of the maxSpeed of the shipclass, the value is a % of the lightspeed. (so lightspeed is 100)
Example:
[code](shpGetMaxSpeed gPlayership)[/code]
Returns 18 if the player is using the Freighter.
Comment:
Useful function to check the maximum speed of a ship.
Name:
shpGetOrder
Syntax:
(shpGetOrder ship)
Argument List:
ship: The ship that you want the order from.
Returns:
string: A string representation of the ships current order.
Category:
ship, orders
Description:
Returns what orders the ship is currently under.
Example:
Comment:
Useful for checking if a ship is busy or if it is ready for new orders.
Name:
shpGetOrderDesc
Syntax:
(shpGetOrderDesc obj) -> orderDesc
Argument List:
obj: the spaceobject
Returns:
orderDesc: the description of the orders
Category:
spaceobject, ship
Description:
Not used in Transcendence.tdb
Example:
Comment:
Name:
shpGetOrderTarget
Syntax:
(shpGetOrderTarget obj) -> obj
Argument List:
obj: the spaceobject to get the target of
Returns:
the spaceobject the obj is targeting
Category:
spaceobject, ship
Description:
Use to get the target of a spaceobjects order, say, the object it is guarding, attacking or escorting.
Example:
taken from &intZoanthropeOnOrderChanged;
[code]
(block (prevLeader newLeader)
; Register for the new leader
(setq newLeader (shpGetOrderTarget gSource))
(objSetObjRefData gSource "leader" newLeader)
(objRegisterForEvents gSource newLeader)
)
[/code]
Comment:
Name:
shpGetShieldDamage
Syntax:
(shpGetShieldDamage ship)
Argument List:
ship: The ship that you want get the amount of damage the shields have.
Returns:
number: The amount of damage the ship's shield has.
Category:
repair/damage, ship, shield
Description:
Returns the amount of damage the ship's shield has.
Example:
Comment:
Used to see if the ship is fully charged.
Name:
shpGetShieldItemUNID
Syntax:
(shpGetShieldItemUNID ship)
Argument List:
ship: The ship that you want get the UNID the shields have.
Returns:
number: The UNID of the ship's shield.
Category:
ship, shield, unid
Description:
Returns the UNID of the ship's shield.
Example:
Comment:
Can be used for interesting things like a disguising shield.
Name:
shpGetShieldMaxHitPoints
Syntax:
(shpGetShieldMaxHitPoints ship)
Argument List:
ship: The ship that you want get the max hit point the shields have.
Returns:
number: The max hit points of the ship\'s shield.
Category:
ship, shield
Description:
Returns the max hit points of the ship\'s shield.
Example:
Comment:
Not used in the xml files but still works fine.
Name:
shpInstallArmor
Syntax:
(shpInstallArmor ship itemStruct number)
Argument List:
ship: The ship that you want install the armor.
itemStruct: The armor you want to install.
number: Where on the ship you want to install the armor. 0 is the first location in the ship's armor tag.
Returns:
condition: True is successful.
Category:
ship, armor, install
Description:
Attempts to install the pointed to armor in the location.
Example:
(shpInstallArmor gPlayership (itmCreate &itUltraLightTitaniumPlate; 1) 0)
Comment:
Name:
shpInstallAutopilot
Syntax:
(shpInstallAutopilot ship)
Argument List:
ship: The ship that you want install the auto pilot.
Returns:
condition: True is successful, Nil otherwise.
Category:
enhancement, ship
Description:
Attempts to install the auto pilot.
Example:
[code](shpInstallAutopilot gplayership)[/code]
Returns Nil. The player ships starts with auto pilot installed.
Comment:
No use in the current build do to the player ship has the auto pilot already installed at the start of the game.
Name:
shpInstallDevice
Syntax:
(shpInstallDevice ship expression)
Argument List:
ship: The ship that you want install the device on.
expression: Can take a item struct or an item list pointer. The device to install.
Returns:
condition: True is successful, Nil otherwise.
Category:
install, ship
Description:
Attempts to install the device indicated by the expression. The expression can be an item struct or an item list pointer.
Example:
Comment:
Very important function to allow you to change what is equipped from in code.
Name:
shpInstallTargetingComputer
Syntax:
(shpInstallTargetingComputer ship)
Argument List:
ship: The ship that you want install the targeting computer on.
Returns:
condition: True is successful, Nil otherwise.
Category:
enhancement, ship, install
Description:
Attempts to install a targeting computer on the ship.
Example:
[code](shpInstallTargetingComputer gplayership)[/code]
Attempts to install a targeting computer on the players ship.
Comment:
Limited use but the targeting computer is a very useful thing in game.
Name:
shpIsAutopilotInstalled
Syntax:
(shpIsAutopilotInstalled ship)
Argument List:
ship: The ship that you want check if it has an auto pilot.
Returns:
condition: True if the ship has an auto pilot, Nil otherwise.
Category:
enhancement, ship, condition query
Description:
[code](shpIsAutopilotInstalled gplayership)[/code]
Returns True due to the fact the player's ship starts with an auto pilot.
Example:
[code](shpIsAutopilotInstalled gplayership)[/code]
Returns True due to the fact the player's ship starts with an auto pilot.
Comment:
No use in the current build do to the player ship has the auto pilot already installed at the start of the game.
Name:
shpIsFuelCompatible
Syntax:
(shpIsFuelCompatible ship fuelItem)
Argument List:
ship: The ship that you want check if the fuel is compatible.
fuelItem: The item struct of the fuel you want to check.
Returns:
condition: True if the fuel is compatible with the ship, Nil otherwise.
Category:
reactor, condition query, ship, fuel
Description:
Returns true if the fuel is compatible with the ship and its reactor.
Example:
Comment:
Nice simple function allowing you to check if the fuel is compatible with the ship.
Name:
shpIsRadiationImmune
Syntax:
(shpIsRadiationImmune ship [itemListCursor])
Argument List:
ship: The ship that you want check if it is radiation immune.
itemListCursor: The optional location of the armor to check.
Returns:
condition: True if the armor pointed too compatible with the ship, if no armor is pointed to checks all the armor and if all are immune returns True, Nil otherwise.
Category:
radiation, condition query, ship
Description:
Checks to see if the ship is radiation immune.
Example:
Comment:
Basic query function to check if a ship is radiation immune.
Name:
shpIsRadioactive
Syntax:
(shpIsRadioactive ship)
Argument List:
ship: The ship that you want check if it is radioactive.
Returns:
condition: True if the ship is radioactive, Nil otherwise.
Category:
deprecated, ship, condition query, radiation
Description:
Checks to see if the ship is radioactive.
Example:
[code](shpIsRadioactive gplayership)[/code]
Checks to see if the player's ship is radioactive and returns the result.
Comment:
DEPRECATED in 1.04: use objIsRadioactive instead.
Basic query function to check if a ship is radioactive.
Name:
shpIsSRSEnhanced
Syntax:
(shpIsSRSEnhanced ship)
Argument List:
ship: The ship that you want check if it's SRS is enhanced.
Returns:
condition: True if the ship's SRS is enhanced, Nil otherwise.
Category:
enhancement, ship, condition query
Description:
Checks to see if the ship's SRS is enhanced.
Example:
[code](shpIsSRSEnhanced gplayership)[/code]
Checks to see if the player's ship's SRS is enhanced and returns the result.
Comment:
Basic query function to check if a ship's SRS is enhanced.
Name:
shpIsTargetingComputerInstalled
Syntax:
(shpIsTargetingComputerInstalled ship)
Argument List:
ship: The ship that you want check if it's targeting computer is installed.
Returns:
condition: True if the ship's targeting computer is installed, Nil otherwise.
Category:
enhancement, ship, condition query
Description:
Checks to see if the ship's targeting computer is installed.
Example:
[code](shpIsTargetingComputerInstalled gplayership)[/code]
Checks to see if the player's ship's targeting computer is installed and returns the result.
Comment:
Basic query function to check if a ship's targeting computer is installed.
Name:
shpMakeBlind
Syntax:
(shpMakeBlind ship number)
Argument List:
ship: The ship that you want to make blind.
number: How long in ticks you want to make the ship blind.
Returns:
condition: True if successful, Nil otherwise.
Category:
repair/damage, ship
Description:
Makes the ship blind for the given number of ticks.
Example:
[code](shpMakeBlind gplayership 300)[/code]
Makes the player blind for 300 ticks.
Comment:
Interesting function allowing you to give a punishment.
Name:
shpMakeRadioactive
Syntax:
(shpMakeRadioactive ship)
Argument List:
ship: The ship that you want to make radioactive.
Returns:
condition: True if successful, Nil otherwise.
Category:
ship, radiation
Description:
Makes the ship radioactive.
Example:
[code](shpMakeRadioactive gplayership)[/code]
Makes the player's ship radioactive.
Comment:
Interesting function allowing you to give a punishment.
Name:
shpOrder
Syntax:
(shpOrder ship order [target] [count]) -> True/Nil
Argument List:
ship: The ship that you want to order.
order: A string representing the order.
[target]: optional target. Only used by some order types.
[count]: Optional count. Only used by some order types. Depending on the order it can represent a timeframe or a distance.
Returns:
True/Nil depending on success.
Category:
orders, ship
Description:
Gives the ship the order. Multiple orders can be queued and they will be completed in sequence.
Example:
[code](shpOrder gPlayerShip 'wait)[/code]
Returns True, although ordering the player to wait doesn't do much.
Comment:
See here for a list of orders:http://wiki.neurohack.com/transcendence/wiki/modding/function/legend#ship_orders
Name:
shpOrderAttack_deprecated
Syntax:
(shpOrderAttack_deprecated ship ship)_deprecated
Argument List:
ship: The ship that you want to order to attack.
ship: The target.
Returns:
condition: True if successful, Nil otherwise.
Category:
ship, deprecated, orders
Description:
Gives the ship the order attack.
DEPRECATED: Use (shpOrder ship 'attack target) instead
Example:
Comment:
Allows you to give orders to ships.
Name:
shpOrderDock_deprecated
Syntax:
(shpOrderDock_deprecated ship spaceObject)_deprecated
Argument List:
ship: The ship that you want to order to dock.
spaceObject: The target to dock with.
Returns:
condition: True if successful, Nil otherwise.
Category:
deprecated, orders, ship
Description:
Gives the ship the order dock.
DEPRECATED: Use (shpOrder ship 'dock target) instead
Example:
Comment:
Allows you to give orders to ships.
Name:
shpOrderEscort_deprecated
Syntax:
(shpOrderEscort_deprecated ship protect [formation]) -> True/Nil_deprecated
Argument List:
ship: The ship that you want to order to escort.
protect: The target to escort.
[formation]: an optional value that represents the ships position in formation.
Returns:
condition: True if successful, Nil otherwise.
Category:
deprecated, ship, orders
Description:
Gives the ship the order escort and protect another ship.
DEPRECATED: Use (shpOrder ship 'escort obj [formation]) instead
Example:
Comment:
Allows you to give orders to ships.
Name:
shpOrderFollow_deprecated
Syntax:
(shpOrderFollow_deprecated ship spaceObject)_deprecated
Argument List:
ship: The ship that you want to order to follow.
spaceObject: The target to follow.
Returns:
condition: True if successful, Nil otherwise.
Category:
deprecated, orders, ship
Description:
Gives the ship the order follow the spaceObject.
DEPRECATED: Use (shpOrder ship 'follow target) instead
Example:
Comment:
Allows you to give orders to ships.
Name:
shpOrderGate_deprecated
Syntax:
(shpOrderGate_deprecated ship [spaceObject])_deprecated
Argument List:
ship: The ship that you want to order to gate.
spaceObject: The star gate you want to gate at.
Returns:
condition: True if successful, Nil otherwise.
Category:
deprecated, orders, ship
Description:
Gives the ship the order gate out.
DEPRECATED: Use (shpOrder ship 'gate [gate]) instead
Example:
Comment:
Allows you to give orders to ships.
Name:
shpOrderGoto_deprecated
Syntax:
(shpOrderGoto_deprecated ship spaceObject)_deprecated
Argument List:
ship: The ship that you want to fly to a position.
spaceObject: an object the ship will fly to.
Returns:
condition: True if successful, Nil otherwise.
Category:
deprecated, orders, ship
Description:
Gives the ship an order to fly to the spaceObject.
DEPRECATED: Use (shpOrder ship 'goto obj) instead
Example:
Comment:
Allows you to give orders to ships.
Name:
shpOrderGuard_deprecated
Syntax:
(shpOrderGuard_deprecated ship spaceObject)_deprecated
Argument List:
ship: The ship that you want to order to guard.
spaceObject: The target to guard.
Returns:
condition: True if successful, Nil otherwise.
Category:
orders, deprecated, ship
Description:
Gives the ship the order guard the spaceObject.
DEPRECATED: Use (shpOrder ship 'guard target) instead
Example:
Comment:
Allows you to give orders to ships.
Name:
shpOrderHold_deprecated
Syntax:
(shpOrderHold_deprecated ship [number])_deprecated
Argument List:
ship: The ship that you want to order to hold position.
number: How long to hold position.
Returns:
condition: True if successful, Nil otherwise.
DEPRECATED: Use (shpOrder ship 'hold [time]) instead
Category:
ship, deprecated, orders
Description:
Gives the ship the order hold position.
Example:
Comment:
Allows you to give orders to ships.
Name:
shpOrderImmediate
Syntax:
(shpOrderImmediate ship order [target] [count]) -> True/Nil
Argument List:
ship: The ship that you want to order.
order: A string representing the order.
[target]: optional target. Only used by some order types.
[count]: Optional count. Only used by some order types. Depending on the order it can represent a timeframe or a distance.
Returns:
True/Nil depending on success
Category:
orders, ship, 1.04
Description:
Gives an order to a ship, just like the regular shpOrder function. The difference is that it inserts it at the top of the order stack. The ship will delay the current order, execute the order given with this function and then return to its previous order
Example:
[code](shpOrderImmediate target 'hold 60)[/code]
Causes target to hold its current position for 2 seconds and then continue.
Comment:
First available in 1.04
Name:
shpOrderLoot_deprecated
Syntax:
(shpOrderLoot_deprecated ship spaceObject)_deprecated
Argument List:
ship: The ship that you want to order to loot.
spaceObject: The target to loot.
Returns:
condition: True if successful, Nil otherwise.
Category:
orders, deprecated, ship
Description:
Gives the ship the order loot the target.
DEPRECATED: Use (shpOrder ship 'loot obj) instead
Example:
Comment:
Allows you to give orders to ships.
Name:
shpOrderMine_deprecated
Syntax:
(shpOrderMine_deprecated ship spaceObject)_deprecated
Argument List:
ship: The ship that you want to order to mine.
spaceObject: The target to return the mined ore too.
Returns:
condition: True if successful, Nil otherwise.
Category:
deprecated, ship, orders
Description:
Gives the ship the order mine and return the ore to the spaceObject.
DEPRECATED: Use (shpOrder ship 'mine baseObj) instead
Example:
Comment:
Allows you to give orders to ships.
Name:
shpOrderPatrol_deprecated
Syntax:
(shpOrderPatrol_deprecated ship spaceObject number)_deprecated
Argument List:
ship: The ship that you want to order to patrol.
spaceObject: What to patrol around.
number: How far out to patrol.
Returns:
condition: True if successful, Nil otherwise.
Category:
deprecated, ship, orders
Description:
Gives the ship the order to patrol around a space object.
DEPRECATED: Use (shpOrder ship 'patrol baseObj dist) instead
Example:
Comment:
Allows you to give orders to ships.
Name:
shpOrderWait_deprecated
Syntax:
(shpOrderWait_deprecated ship number)_deprecated
Argument List:
ship: The ship that you want to order to wait.
number: How long you want the ship to wait.
Returns:
condition: True if successful, Nil otherwise.
Category:
deprecated, orders, ship
Description:
Gives the ship the order to wait.
DEPRECATED: Use (shpOrder ship 'wait [time]) instead
Example:
Comment:
Allows you to give orders to ships.
Name:
shpRechargeItem
Syntax:
(shpRechargeItem ship expression number)
Argument List:
ship: The ship that has the item to recharge.
expression: An item struct or item list pointer to the item you want to recharge.
number: The number of charges you want to add to the item.
Returns:
condition: True if successful, Nil otherwise.
Category:
ship, item
Description:
Adds the given number of charges to the item on the ship.
Example:
Comment:
As with the other charge function I don't know why it is part of the ship functions.
Name:
shpRechargeShield
Syntax:
(shpRechargeShield ship number)
Argument List:
ship: The ship that has a shield to recharge.
number: The amount you want to recharge.
Returns:
condition: True if successful, Nil otherwise.
Category:
ship, shield, repair/damage
Description:
Recharges the ships shields the given amount. Does not recharge over the shields max hp.
Example:
[code](shpRechargeShield gplayership 10)[/code]
Adds ten hp to the player's shield.
Comment:
Useful for repairing a shield from in code.
Name:
shpRefuelFromItem
Syntax:
(shpRefuelFromItem ship itemStruct)
Argument List:
ship: The ship that want to refuel from an item.
itemStruct: The item you want to use.
Returns:
boolean: True if successful, Nil otherwise.
Category:
fuel, ship, item
Description:
Refuels the ship from the given item struct.
Example:
[code](shpRefuelFromItem gplayership (itmCreate &itHelium3FuelRod; 1))[/code]
Adds 2500 to the player's fuel.
Comment:
This function is not limited by reactor fuel level limits; it must be guarded by shpIsFuelCompatable if enforcing those limits is deisred.
The item struct is just used to determine the quantity of fuel to add; the items provided are not removed from the ship and need not even be present.
Name:
shpRemoveDevice
Syntax:
(shpRemoveDevice ship expression)
Argument List:
ship: The ship that want to uninstall an device on.
expression: The item you want to uninstall, can be a item struct or item list pointer.
Returns:
condition: True if successful, Nil otherwise.
Category:
ship, item, install
Description:
Uninstalls the given item from the ship.
Example:
Comment:
Some cool effects can be done like having random items or an item that removes other items.
Name:
shpRepairItem
Syntax:
(shpRepairItem ship itemListCursor)
Argument List:
ship: The ship that want to repair an item on.
itemListCursor: The itemListCursor of the item you want to repair.
Returns:
condition: True if successful, Nil otherwise.
Category:
item, repair/damage, ship
Description:
Repairs the given item on the ship.
Example:
Comment:
Helpful in repairing damaged items.
Name:
shpSetAISetting
Syntax:
(shpSetAISetting ship setting value)
Argument List:
ship: the ship to affect
setting: the AI setting to change
value: the value to set the AI setting to
Returns:
unsure
Category:
ship, spaceobject, 1.06
Description:
Used to change the setting of an AI ship.
Example:
Currently not used in the Transcendence.tdb
Comment:
Look at the AISettings section of ships for examples of the values to get and set.
Name:
shpSetCommandCode
Syntax:
(shpSetCommandCode targetShip commandCode) -> True/Nil
Argument List:
targetShip: the ship that you want to set the command code for.
commandCode: the specific command code to set.
Returns:
True/Nil depending on success
Category:
ship, orders
Description:
Allows you to change the behaviour of a ship. The commandCode is a block if code that will be executed when the ship has no pending orders, or when shpCancelOrders is called. You can use gSource to refer to the targetShip inside this block
Example:
See BattleArena.xml in Vanilla Transcendence for an example
Comment:
Name:
shpSetController
Syntax:
(shpSetController ship string)
Argument List:
ship: The ship that want to change the ai on.
string: The name of the controller.
Returns:
condition: True if successful, Nil otherwise.
Category:
ship, ai
Description:
Changes the ai of the ship.
Example:
[code](shpSetController gSource "auton")[/code]
Makes the calling ship act like an auton.
Comment:
Very interesting function allowing you to change the way a ship behaves.
Possible values are "auton", "fleet", "fleetcommand", "ferian"
Name:
shpSetGlobalData_deprecated
Syntax:
(shpSetGlobalData_deprecated number string expression)
Argument List:
number: The UNID of the ship class you want to set the global data on.
string: The name of the global data.
expression: The data you want to store.
Returns:
condition: True if successful, Nil otherwise.
Category:
data, ship, 0.98
Description:
Sets the global data of a ship.
Example:
[code](shpSetGlobalData &scCSCTerra; "antarctica" "betrayed")[/code]
Sets the global data of the CSC Terra named antarctica to betrayed.
Comment:
Basic data function allowing you to set global data with a UNID instead of a space object.
DEPRECATED: Use typSetGlobalData instead
Name:
shpSetPlayerWingman
Syntax:
(shpSetPlayerWingman ship [isWingman]) -> True/Nil
Argument List:
ship: the ship to set as a player wingman
[isWingman]: unsure
Returns:
Boolean: true or nil depending upon success
Category:
spaceobject, ship
Description:
Used to set ships as wingmen.
Example:
Taken from &baStdWingmanBase;
[code]
(block Nil
(shpSetPlayerWingman gSource)
(objSetGlobalData gSource "status" 'joined)
)
[/code]
Comment:
Name:
shuffle
Syntax:
(shuffle list)
Argument List:
list: The list you want to put in random order.
Returns:
list: A list containing the same elements as the passed in list but in a random order.
Category:
0.99, list, random
Description:
Makes a new list based on the passed in lists elements ordered randomly.
Example:
[code](shuffle '(a b c d e))[/code]
Can return the list (c d e b a)
Comment:
Useful in shuffling the first level of a list.
Name:
sort
Syntax:
(sort list [direction] [keyIndex]) -> list
Argument List:
list: the list to be sorted
[direction:] the direction in which to sort the list. Can be either 'ascending or 'descending
[keyIndex:] if you have a list of lists and you want to sort by an element of a sublist, specify the keyindex of that element
Returns:
list: the sorted list
Category:
list
Description:
Very useful function for sorting lists of data
Example:
You can sort a list of numbers
[code]
(setq numbers (list 8 7 9 4 6 1))
(sort numbers) -> (1 4 6 7 8 9)
(sort numbers 'descending) -> (9 8 7 6 4 1)
[/code]
You can sort a list of strings (alphabetically)
[code]
(setq strings (list "a" "t" "f" "x"))
(sort strings) -> ("a" "f" "t" "x")
(sort strings 'descending) -> ("X' "t" "f" "a")
[/code]
You can also sort sublists
[code]
(setq sublists (list
(list 5 'five)
(list 3 'three)
(list 9 'nine)
))
(sort sublists 'ascending 0) -> ((3 'three) (5 'five) (9 'nine))
(sort sublists 'ascending 1) -> ((5 'five) (9 'nine) (3 'three))
[/code]
Comment:
Name:
sovGetDisposition
Syntax:
(sovGetDisposition sovereignID targetSovereignID) -> disposition of sovereign to target
Argument List:
sovereignID:
targetSovereignID:
Returns:
disposition of sovereign to target
Category:
sovereign
Description:
Used to get the dispositions of sovereigns.
Example:
taken from &stFerianColony;
[code]
(if (and aOrderGiver
(objCanAttack aOrderGiver)
(not (eq
(sovGetDisposition &svFerianMiners;
(objGetSovereign aOrderGiver)) 'friend))
)
(block Nil
(objIncData gSource "attackLevel" 2)
(if (or (not (objGetObjRefData gSource "lastAttacker"))
(leq (random 1 100) 50)
)
(objSetObjRefData gSource "lastAttacker" aOrderGiver)
)
)
)
[/code]
Comment:
Name:
sovSetDisposition
Syntax:
(sovSetDisposition sovUNID1 sovUNID2 disposition)
Argument List:
sovUNID1: The UNID of the sovereign to change disposition of.
sovUNID2: The UNID of the sovereign to change disposition towards
disposition: (string) the first sovereigns disposition towards the other
Returns:
condition: True if successful, Nil otherwise.
Category:
sovereign, ai
Description:
Sets the disposition of the first sovereign to the second sovereign.
Valid dispositions are "enemy", "neutral" and "friend"
Example:
[code](sovSetDisposition &svCSCAntarctica; &svPlayer; 0)[/code]
Makes things controlled by the Antarctica sovereign attack the player.
Comment:
Interesting function allowing you to change how different groups of space objects act toward each other.
Name:
sqrt
Syntax:
(sqrt number)
Argument List:
number: The number you want to find the square root to.
Returns:
number: The square root of the given number. It will be truncated at the decimal point.
Category:
0.99, math
Description:
Finds the square root of the given number.
Example:
[code](sqrt 1000)[/code]
Returns 31.
Comment:
Helpful math function. Only finds the first digit.
Name:
staClearFireReconEvent
Syntax:
(staClearFireReconEvent station)
Argument List:
station: The station you want to clear the recon event from.
Returns:
condition: True if successful, Nil otherwise.
Category:
station, event, recon
Description:
Stops the recon event from being called on the station.
Example:
Comment:
Used to remove what staSetFireReconEvent sets. You recon something if you have seen it on screen.
Name:
staClearReconned
Syntax:
(staClearReconned station)
Argument List:
station: The station you want not to be reconned anymore.
Returns:
condition: True if successful, Nil otherwise.
Category:
station, recon
Description:
Makes the station not to be reconned anymore.
Example:
Comment:
You recon something if you have seen it on screen.
Name:
staGetDockedShips
Syntax:
(staGetDockedShips station)
Argument List:
station: The station that you want to query.
Returns:
list: the list of docked ships.
Category:
ship, station
Description:
Returns the list of ships that are docked to the queried station.
Example:
Comment:
Currently used in the Korolov shipping code to select a docked ships for the missions.
Name:
staGetGlobalData_deprecated
Syntax:
(staGetGlobalData_deprecated number string)
Argument List:
number: The UNID of the station you want to get the data from.
string: The name of the data.
Returns:
data: Whatever the named global data in the station type contains.
Category:
data, station
Description:
Returns the data named by the string for the station type.
Example:
[code](staGetGlobalData &stCSCEuropaWreck; "VaultCode")[/code]
Returns what is in the VaultCode in the CSC Europa.
Comment:
Basic data function allowing you to get global data with a UNID instead of a space object.
DEPRECATED: Use typGetGlobalData instead
Name:
staGetImageVariant
Syntax:
(staGetImageVariant station)
Argument List:
station: The station you want to get the image variant of.
Returns:
number: The number of the image variant.
Category:
station
Description:
Gets the image variant of the station.
Example:
Comment:
Useful for seeing what image variant a station is using.
Name:
staGetMaxStructuralHP
Syntax:
(staGetMaxStructuralHP station) -> hp
Argument List:
station: the station to check for max structural HP
Returns:
number: the structural HP of the station
Category:
station
Description:
Used to get the max structural HP of a station.
Example:
Taken from &intContainerOnDamage;
[code]
; Compute the how powerful the damage is;
100 = enough to destroy all HP
(setq maxHP (staGetMaxStructuralHP theObj))
(if (gr maxHP 0)
(setq damageAdj (max 1 (divide (multiply 100 damageHP) maxHP)))
(block Nil
(setq damageAdj 1)
(setq maxHP 1)
)
)
[/code]
Comment:
Name:
staGetStructuralHP
Syntax:
(staGetStructuralHP station)
Argument List:
station: The station you want to get the structural hp of.
Returns:
number: The structural hp of the station.
Category:
station
Description:
Returns the structural hp of the station.
Example:
Comment:
The structural HP of a station is how many HP before it is completely destroyed.
Name:
staGetSubordinates
Syntax:
(staGetSubordinates station)
Argument List:
station: The station that you want the subordinates from.
Returns:
list: the list of spaceObjects subordinates.
Category:
station, spaceobject
Description:
Returns the list of spaceObjects that are subordinates of the queried station. These include ships and satellites.
Example:
[code](staGetsubordinates (sysCreateStation &stStartonEridani; Nil))[/code]
Returns the list of subordinates of the newly created Starton Eridani.
Comment:
Basic and interesting function used only for the Centauri occupied station.
Name:
staGetType
Syntax:
(staGetType station)
Argument List:
station: The station you want to set the UNID of.
Returns:
number: The UNID of the station.
Category:
station, unid
Description:
Returns the UNID of the station.
Example:
[code](staGetType (sysCreateStation &stStartonEridani; Nil))[/code]
This will return the number 1056769.
Comment:
Useful for seeing the UNID of a station.
Name:
staIsEncountered
Syntax:
(staIsEncountered number)
Argument List:
number: The UNID of the station you want to check if it has been created.
Returns:
condition: True if the station has been created before, Nil otherwise.
Category:
condition query, station, unid
Description:
Checks if the station has been created before.
Example:
[code](staIsEncountered &stStartonEridani;)[/code]
Returns true because one is created in the first system.
Comment:
Useful in checking if a station already exists in the game.
Name:
staIsReconned
Syntax:
(staIsReconned station)
Argument List:
station: The station you want check if it is reconned.
Returns:
condition: True if the station has been reconned, Nil otherwise.
Category:
station, recon, condition query
Description:
Returns if the station has been reconned.
Example:
Comment:
You recon something if you have seen it on screen.
Name:
staSetActive
Syntax:
(staSetActive station)
Argument List:
station: The station you want to set active.
Returns:
condition: True if successful, Nil otherwise.
Category:
station
Description:
Sets the data in the station named by "Active" to true and allows the station to be animated.
Example:
Comment:
Used for the last star gate.
Name:
staSetFireReconEvent
Syntax:
(staSetFireReconEvent station)
Argument List:
station: The station you want fire events when it is reconned.
Returns:
condition: True if successful, Nil otherwise.
Category:
station, event, recon
Description:
Makes the station fire recon events when it is reconned.
Example:
Comment:
Used with OnObjReconned. You recon something if you have seen it on screen.
Name:
staSetGlobalData_deprecated
Syntax:
(staSetGlobalData_deprecated number string expression)
Argument List:
number: The UNID of the station you want to set the data on.
string: The name of the data.
expression: The data you want to store.
Returns:
condition: True if successful, Nil otherwise.
Category:
station, data, 0.98
Description:
Stores the expression in the named global data in the station type.
Example:
[code](staSetGlobalData &stCSCEuropaWreck; "VaultCode" (cat (random codes) " " (random codes) " " (random 1 999)))[/code]
Sets the random code in the VaultCode in the CSC Europa.
Comment:
Basic data function allowing you to set global data with a UNID instead of a space object.
DEPRECATED: Use typSetGlobalData instead
Name:
staSetImageVariant
Syntax:
(staSetImageVariant station number)
Argument List:
station: The station you want to set the image variant of.
number: The number of the image variant you want to change it to.
Returns:
condition: True if successful, Nil otherwise.
Category:
station
Description:
Sets the image variant of the station.
Example:
Comment:
Useful for changing what image variant a station is using.
Name:
staSetInactive
Syntax:
(staSetInactive station)
Argument List:
station: The station you want to set inactive.
Returns:
condition: True if successful, Nil otherwise.
Category:
station
Description:
Sets the data in the station named by "Active" to Nil and stops the station from being animated.
Example:
Comment:
Useful for stopping animations on a station.
Name:
staSetShowMapLabel
Syntax:
(staSetShowMapLabel station True/Nil)
Argument List:
station: the station to show or not show map labels
True/Nil: True to show a label, nil to not show a label.
Returns:
unsure
Category:
station
Description:
Used to show/hide station map labels. Labels show up on the map.
Example:
taken from &ssHeretic;
[code]
; Do not show a map label
(staSetShowMapLabel theObj Nil)
[/code]
Comment:
Name:
staSetStructuralHP
Syntax:
(staSetStructuralHP station number)
Argument List:
station: The station you want to set the structural hp of.
number: What you want to set the structural hp to.
Returns:
condition: True if successful, Nil otherwise.
Category:
station
Description:
Sets the structural hp of the station.
Example:
Comment:
The structural HP of a station is how many HP before it is completely destroyed.
Name:
strCapitalize
Syntax:
(strCapitalize string) -> capitalizedString
Argument List:
string: The string that you want the first character capitalized.
Returns:
capitalizedString: The passed in string with the first character capitalized.
Category:
string operator
Description:
Capitalizes the first character of the string.
Example:
[code](strCapitalize "abcdef")[/code]
Returns the string Abcdef.
Comment:
Basic string function. We need more string functions.
Name:
strFind
Syntax:
(strFind string string)
Argument List:
string: The string that to search.
string: The string you want to search for.
Returns:
number: The index where the second string is found starting at 0, if not found returns Nil.
Category:
string operator
Description:
Finds the second string in the first string and returns where it is in the first string.
Example:
[code](strFind "abcdef" "ab")[/code]
Returns the number 0.
[code](strFind "abcdef" "cd")[/code]
Returns the number 2.
[code](strFind "abcdef" "Betel")[/code]
Returns Nil.
Comment:
Interesting string function allowing you to search in strings. We need more string functions.
NOTE: The function is not case sensitive.
Name:
subst
Syntax:
(subst string string^1)
Argument List:
string: A string that contains %number% parts.
string: The strings you are inserting into the first string.
^1
Returns:
string: The string with the appropriate parts replaced.
Category:
string operator
Description:
Replaces the %number% parts of the first string with the element referenced by that number in the argument list and returns it. Can have unused arguments.
Example:
[code](subst "%1% and %4% and %3% and %4%" "runs" 5000 "four" "bob" "not used")[/code]
Returns the string "runs and bob and four and bob".
[code](subst "%8% %7% %6% %5% %4% %3% %2% %1%." "function" "subst" "the" "of" "example" "an" "is" "This")[/code]
Returns the string "This is an example of the subst function.".
Comment:
The xml wasn't much help in seeing what this does. Remember numbers can be strings if needed in Transcendence. %0% means %
Name:
subtract
Syntax:
(subtract number number)
Argument List:
number: The first number you want subtracted.
number: The second number you want subtracted.
Returns:
number: The number that results when you subtracts the two numbers.
Category:
math
Description:
Subtracts the two numbers.
Example:
[code](subtract 34 0x20)[/code]
Returns the number 2.
Comment:
Basic math function.
Name:
switch
Syntax:
(switch [exp1 exp2] ... [expn expn1] [defaultexp]) -> value of evaluated expression
Argument List:
[exp1 exp2] ... [expn expn1]: A group of two expressions following each other. It the first expression evaluates to non-Nil, then the second expression is evaluated. Else the switch moves on to test the next group. There can be as many of these groups as neccessary.
[defaultexp]: an expression which will be evaluated if no group was successfully evaluated. This expression can be considered the "default" of the switch.
Returns:
Whatever the expression that gets evaluated returns.
Category:
control structure
Description:
Allows branching of the code by more than 1 condition. For just 1 condition, 'if' is good enough. It just evaluates all the conditions (every even argument; odd arguments are corresponding functions) in left to right order, until the first one that evaluates to non-Nil. It then invokes the corresponding function, which is the argument that directly follows that condition. If all the conditions evaluate as Nil, then the last, optional function is invoked.
Example:
[code]
(setq num 3)
(switch
(eq num 1)
(plyMessage gPlayer "num = 1")
(eq num 2)
(plyMessage gPlayer "num = 2")
(eq num 3)
(plyMessage gPlayer "num = 3")
(eq num 4)
(plyMessage gPlayer "num = 4")
(plyMessage gPlayer "num not in (1,2,3,4)")
)
[/code]
Comment:
Useful for various multiple choices in the code. In could be replaced by series of 'if's but then there would be even more parentheses than now. Also, it's interesting to notice that there probably isn't any real difference between 'expressions', 'functions' and 'optional function': these are legal switch function examples:
(switch 1 11 2 12 3 13 4 14 5 15) -> 11
(switch Nil 11 Nil 12 3 13 4 14 5) -> 13
(switch Nil 11 Nil 12 Nil 13 Nil 14 5) -> 5
So it just takes a list of arguments, evaluates the first one, if it's non-Nil, evaluates the second and returns whatever it is. If the first argument is Nil, skips the second and evaluates the third; if that one is non-Nil, evaluates the fourth and returns, etc. The 'optional function' might also be considered just another condition, which doesn't have a following argument, thus (switch Nil 11 Nil 12 3) evaluates as 3. It really is simple when you look at it this way.
Name:
sysAddEncounterEvent
Syntax:
(sysAddEncounterEvent number spaceObject number spaceObject)
Argument List:
number: The delay before the encounter event can happens.
spaceObject: The space object the encounter ships target.
number: The UNID of the encounter table.
spaceObject: The spaceObject where you want the encounter ship to appear at.
Returns:
condition: True if successful, Nil otherwise.
Category:
system, encounter table, time
Description:
Makes a encounter at the given space object.
Example:
[code](sysAddEncounterEvent 100 gplayership &etPirateAmbush1; gplayership)[/code]
Makes a pirate ambush 1 encounter 100 ticks after this is called on the player ship targeting the player ship.
Comment:
Can be used to mimic random encounters. Is mostly used to make ambushes happen.
Name:
sysAddEncounterEventAtDist
Syntax:
(sysAddEncounterEventAtDist number spaceObject number number)
Argument List:
number: The delay before the encounter event can happens.
spaceObject: The space object the encounter ships target.
number: The UNID of the encounter table.
number: The distance from the target you want the encounter ships to appear at.
Returns:
condition: True if successful, Nil otherwise.
Category:
system, encounter table, time
Description:
Makes a encounter at the given distance from the space object.
Example:
[code](sysAddEncounterEventAtDist 100 gplayership &etPirateAmbush1; 100)[/code]
Makes a pirate ambush 1 encounter 100 ticks after this is called 100 light seconds from player ship targeting the player ship.
Comment:
Can be used to mimic random encounters. Is mostly used to make ambushes happen.
Name:
sysAddObjRecurringTimerEvent
Syntax:
(sysAddObjRecurringTimerEvent number spaceObject string)
Argument List:
number: The ticks between each of the timed events.
spaceObject: The space object that will be calling the events.
string: The name of the event.
Returns:
condition: True if successful, Nil otherwise.
Category:
system, event, time
Description:
Makes an event be called on a space object every so often.
Example:
[code](sysAddObjRecurringTimerEvent 100 gplayership "Success")[/code]
Calls the event called Success on the player ship every 100 ticks.
Comment:
Allows you to run a code every so often.
Name:
sysAddObjTimerEvent
Syntax:
(sysAddObjTimerEvent number spaceObject string)
Argument List:
number: The delay before the event is run.
spaceObject: The space object that will be calling the event.
string: The name of the event.
Returns:
condition: True if successful, Nil otherwise.
Category:
system, event, time
Description:
Makes an event be called on a space object after a delay.
Example:
[code](sysAddObjTimerEvent 100 gplayership "Success")[/code]
Calls the event called Success on the player ship after 100 ticks.
Comment:
Allows you to run a code on an space object after a delay.
Name:
sysAddStargateTopology
Syntax:
(sysAddStargateTopology [nodeID] gateID destNodeID destGateID) -> True/Nil
Argument List:
[nodeID]: the node ID of the star system
gateID: the ID of the gate
destNodeID: the Destination node ID
destGateID: the Destination Gate ID
Returns:
boolean: true or nil depending upon success
Category:
system
Description:
Used to add stargate Topology. Can only be called in the OnGlobalTopologyCreated event
Example:
Taken from &ssHuaramarca;
[code]
(if gateway
(block Nil
(typSetGlobalData &svHuariEmpire; "huaramarcaGateway" gateway)
(sysAddStargateTopology gateway "GateToHuaramarca" "Huaramarca" "Inbound")
)
)
[/code]
Comment:
Name:
sysAddTypeRecurringTimerEvent
Syntax:
(sysAddTypeRecurringTimerEvent interval type event)
Argument List:
interval: time, in ticks, between event triggers
type: UNID of type to call event on
event: name of event to call
Returns:
??
Category:
system, time, type, events
Description:
As sysAddObjRecurringEvent, but causes events to be called on the type itself as onGlobal events are.
Example:
(sysAddTypeRecurringTimerEvent 30 &myType; 'onEachSecond)
Comment:
Timer events are still bound to the system that they're in, you can't just set them once and have them continue for the whole game.
gSource is invalid in the events fired by this function.
Name:
sysAddTypeTimerEvent
Syntax:
(sysAddTypeTimerEvent delay type event)
Argument List:
delay: number of ticks to wait before firing event
type: UNID of type to call event on
event: name of event to call
Returns:
??
Category:
system, time, type, events
Description:
As sysAddTypeTimerEvent, but causes events to be called on the type itself as onGlobal events are.
Example:
(sysAddTypeTimerEvent 30 &myType; 'inOneSecond)
Comment:
Timer events are still bound to the system that they're in, you can't just set them once and have them continue for the whole game.
gSource is invalid in the events fired by this function.
Name:
sysCalcFireSolution
Syntax:
(sysCalcFireSolution targetPos targetVel speed)
Argument List:
targetPos - The vector position of the target
targetVel - The vector velocity of the target
speed - The speed of the projectile
Returns:
angle or Nil
Category:
weapon, math
Description:
A very useful function when using sysCreateWeaponFire. Automactically performs all trigonometry required to properly lead a target (assuming it moves in a straight line at constant speed)
Example:
[code](sysCalcFireSolution (sysVectorSubtract (objGetpos aTargetobj) aFirePos) (objGetVel aTargetObj) (typGetDataField (itmGetUNID gItem) 'speed))[/code]
The above will return the correct angle to fire a projectile in order to hit aTargetObj.
[code](sysCalcFireSolution (sysVectorSubtract (objGetPos aTargetObj) aFirePos) (sysVectorSubtract (objGetVel aTargetObj) (objGetVel gSource)) (typGetDataField (itmGetUNID gItem) 'speed))[/code]
This one will return the correct lead angle to hit aTargetObj when run in the event , unlike the above, this one will factor in the velocity added to the projectile from the movement of the firing ship.
Comment:
(sysCalcFireSolution (sysVectorSubtract (objGetPos Target) gSource) (sysVectorSubtract (objGetVel Target) (objGetVel gSource)) 99999999) can be used to determine the relative angle of any two spaceObjects, Target from gSource in this example.
Name:
sysCalcTravelDistance
Syntax:
(sysCalcTravelDistance speed time) -> distance in light-seconds
Argument List:
speed: the speed of the ship
time: the time travelled
Returns:
number: the distance in light-seconds
Category:
system
Description:
Used to get travel distance in code. It calculates how far could be traveled in the given time with the given speed.
Example:
taken from intComputeRandomEncounterCourse
[code]
; Interception point is wherever the player will be in 100 ticks
(setq interceptPos
(sysVectorPolarOffset theTarget (sysVectorAngle (objGetVel theTarget))
(sysCalcTravelDistance (objGetVel theTarget) 100)
)
)
[/code]
Comment:
Name:
sysCalcTravelTime
Syntax:
(sysCalcTravelTime distance speed) -> time in ticks
Argument List:
distance: the distance the to cover
speed: the speed to travel with
Returns:
number: time in ticks
Category:
system
Description:
Used to get travel times in code. It calculates how long time it will take to travel the given distance at the given speed
Example:
taken from chrRaidTransport
[code]
; Figure out how many ticks it will take for the transport to
; travel the distance
(setq travelTime (sysCalcTravelTime (objGetDistance originObj destObj) (shpGetMaxSpeed transportObj)))
[/code]
Comment:
Name:
sysCancelTimerEvent
Syntax:
(sysCancelTimerEvent spaceObject string)
Argument List:
spaceObject: The space object that will call the event that needs to be canceled.
string: The name of the event.
Returns:
condition: True if successful, Nil otherwise.
Category:
system, event, time
Description:
Stops the named timed event from being called on the space object.
Example:
[code](sysCancelTimerEvent gplayership "Success")[/code]
Stops the timed event Success from running.
Comment:
Allows you to stop a timed event from running.
Name:
sysCancelTypeTimerEvent
Syntax:
(sysCancelTypeTimerEvent type event)
Argument List:
type: UNID of type to cancel event on
event: name of event to cancel
Returns:
??
Category:
system, time, type, events
Description:
As sysCancelObjTimerEvent but works for events set by sysAddType***Event
Example:
(sysCancelTypeTimerEvent &myType; 'eventNoLongerWanted)
Comment:
Timer events are still bound to the system that they're in, you can't just set them once and have them continue for the whole game.
gSource is invalid in the events fired by this function.
Name:
sysCreateEffect
Syntax:
(sysCreateEffect unid spaceObject position)
Argument List:
unid: the UNID of the effect you want to display.
spaceObject: the spaceObject that called the effect, can be a ship or a station or Nil
position: position of the effect
Returns:
condition: True if successful
Category:
unid, system, create
Description:
Creates an effect from the UNID in the desidered position (vector)
Example:
[code](sysCreateEffect &efGemOfSacrifice; gSource (objGetPos gSource))[/code]
Creates the Gem of Sacrifice effect centered on the calling space object
Comment:
Because effects can generate sounds, animations and weapon effects, I think that this function has great modding potential.
Currently used ingame only for the Gem of Sacrifice
Name:
sysCreateEncounter
Syntax:
(sysCreateEncounter classID) -> True/Nil
Argument List:
classID: the unid of the encounter class
Returns:
boolean: true/nil depending upon success
Category:
system
Description:
Used to create an encounter. The class is a station that is set up as an encounter (shipEncounter attribute).
Example:
Comment:
Name:
sysCreateMarker
Syntax:
(sysCreateMarker string vector number)
Argument List:
string: the name of the marker
vector: position of the newly created marker
number: the UNID of the sovereign of the marker
Returns:
spaceobject: the marker the function creates
Category:
create, system, unid
Description:
Creates a marker in the desidered position.
Example:
From &baCharonBuster;
(sysCreateMarker "rally" (sysVectorPolarOffset aBaseObj (random 0 359) (random 16 20)) &svCommonwealth;)
This is the marker used to tell the Charon Busters to wait and form up before they receive the "go code".
Comment:
Basic function used to creates markers, that are invisible spaceObjects used to locate specific positions.
Name:
sysCreateShip
Syntax:
(sysCreateShip shipclass position sovereign [controller])
Argument List:
shipclass: UNID of the ship to create
position: a position or a spaceobject to take the position from, or nil (works as system origin vector)
sovereign: UNID of the new ship's sovereign
[controller]: optional: AI type string, UNID of behaviour class to inherit, or behaviour lambda
Returns:
spaceObject: the created ship
Category:
ship, create, unid
Description:
Creates a ship of the requested class and soverign at the requested position.
Example:
[code]; [From StdAutouns.xml]
; Create the auton
(setq auton
(sysCreateShip
&scAutoSentinel;
(objGetPos gSource)
&svFriendlyAuton;
"auton"
)
)
; Escort ship
(shpOrderEscort auton gSource)[/code]
Comment:
Basic function to create stations in code.
When creating ships from stations, you can use gSource to refer to the station (same when creating from ships)
If you use a object for position, the ship will be created after a short delay (see here: http://neurohack.com/transcendence/forums/viewtopic.php?p=41414#p41414)
The controller is used for adding special behaviour. Currently in use are "fleet" and "auton", but they will be replaced by behaviour classes and behaviour lambdas.
Name:
sysCreateShipwreck
Syntax:
(sysCreateShipwreck classID pos sovereignID) -> shipwreck
Argument List:
classID: the UNID of the ship
pos: the position
sovereignID: the UNID of the sovereign
Returns:
Shipwreck: the spaceobject of the shipwreck
Category:
system
Description:
Used to make shipwrecks.
Example:
taken from &stRingersResearchHeretic;
[code]
(sysCreateShipwreck &scIocrymSentinel;
(sysVectorPolarOffset newObjPos
(random 0 359) 4) &svIndependent;)
[/code]
Comment:
Name:
sysCreateStargate
Syntax:
(sysCreateStargate classID posVector gateID destNodeID destGateID) -> stargate
Argument List:
ClassID: apparently the UNID of the stargate
posVector: the position of the gate
gateID: the gate ID
destNodeID: the Destination ID
destGateID: the destination gate ID (what it links to in the other system)
Returns:
the stargate obj
Category:
system
Description:
Used to create stargates.
Example:
taken from &ssHuaramarca;
[code]
(sysCreateStargate
&stUnchartedMajellenStargate;
(sysVectorRandom Nil (random 1200 1500) 300 "t")
"GateToHuaramarca"
"Huaramarca"
"Inbound"
)
[/code]
Comment:
This thread provides more information on system topology: http://neurohack.com/transcendence/forums/viewtopic.php?f=8&t=4007
Name:
sysCreateStation
Syntax:
(sysCreateStation stationType position) => spaceObject
Argument List:
stationType: the UNID of the station to be create
position: a position vector or nil
Returns:
spaceObject: the created station
Category:
station, create, unid
Description:
Creates a station from its UNID at the desired position
Example:
[code]
; [From Transcendence.xml]
; Create a barricade
(setq barricade
(sysCreateStation barricadeClass
(sysVectorPolarOffset gPlayerShip
(multiply newOrientation 90) 2
)
)
)
[/code]
Comment:
Basic function to create StationType spaceobjects.
Note: unlike sysCreateShip, this function will not take the position of a spaceobject given to it. Use (objGetPosition theObject) if you need that functionality.
Name:
sysCreateWeaponFire
Syntax:
(sysCreateWeaponFire weaponID objSource posVector dir speed objTarget [detonateNow] [weaponBonus]) -> obj
Argument List:
weaponID: the UNID of the called weapon effect
objSource: the spaceObject who is the controller of the weaponfire, can also be Nil
posVector: position of the weaponfire
dir: angle of the direction of the weapon
speed: velocity of the weaponfire
objTarget: the target of the weapon, can also be Nil
[detonateNow]: if True the failsafe variable in the tag is ignored
[weaponBonus]: the bonus damage multiplier, eg from aWeaponBonus if used in
Returns:
obj: The shotObject created by the weapon
Category:
unid, system, create
Description:
Creates the weaponfire effect of a weapon selected from the UNID
Example:
This is a typical example of firing the source weapon (in an OnFireWeapon event) with many of its base attributes intact, ie. firing in the same angle with the same speed. This is for non missile-weapons.
[code](sysCreateWeaponFire (itmGetUNID gItem) gSource aFirePos
aFireAngle (typGetDataField (itmGetUNID gItem) 'speed) aTargetObj)[/code]
This one is for omnidirectional weapons:
[code](block (shot)
(setq shot (sysCreateWeaponFire (itmGetUNID gItem) gSource aFirePos (sysCalcFireSolution (sysVectorSubtract (objGetPos aTargetObj) aFirePos) (sysVectorSubtract (objGetVel aTargetObj) (objGetVel gSource)) (typGetDataField (itmGetUNID gItem) 'speed)) (typGetDataField (itmGetUNID gItem) 'speed) aTargetObj Nil aWeaponBonus))
(objIncVel shot (objGetVel gSource))
)[/code]
Comment:
Highly customizable function that creates weapon fire effects.
The target of the weapon is specified in order to be used for tracking weapons.
Name:
sysFindObject
Syntax:
(sysFindObject source criteria)
Argument List:
source: The spaceObject you want to use as base for some of the criteria. If you pass in Nil, the center of the system will be used.
criteria: The criteria that limits what type of objects to find.
Returns:
list: A list of all the space objects in the current system that match the criteria or Nil. Note that if "N" was in the criteria you wont get a list in return but just a single value.
Category:
system, spaceobject, 0.99
Description:
Returns a list of space objects in the system that match the criteria.
Example:
[code](sysFindObject gPlayerShip "Ts")[/code]
Gives you a list of all structure-scale stations and ships.
Comment:
For a list of criteria see the wiki:
http://wiki.neurohack.com/transcendence/wiki/modding/xml/spaceobject#criteria
Name:
sysGetData
Syntax:
(sysGetData [nodeID] attrib) -> data
Argument List:
[nodeID]: The optional name of the system node. If not given it uses the current system.
attrib: The attribute you want to retrieve the data of.
Returns:
data: Whatever is stored in the attribute in the given node or Nil if no system node exists by that name or the attribute has no data.
Category:
data, system
Description:
Returns the named data for the given system.
Example:
[code](sysGetData "power")[/code]
Returns the currents systems data named by power. If there is no data (like in a unmodded game) by that name returns Nil.
Comment:
Useful for getting/storing information about a system such as how many times the player has visited the system.
Name:
sysGetEnvironment
Syntax:
(sysGetEnvironment spaceObject)
Argument List:
spaceObject: The space object you want to check its environment.
Returns:
number: The unid of the space environment.
Category:
spaceobject, 0.99, unid
Description:
Gets the environment the space object is in.
Example:
[code](sysGetEnvironment gplayership)[/code]
Returns the unid of the environment the player ship is in.
Comment:
Can be very useful in checking what environments space objects are in. Currently not so useful due to we only have one space environment.
Name:
sysGetLevel
Syntax:
(sysGetLevel [string])
Argument List:
[string]: An optional nodeId of the system you want the level of.
Returns:
number: The level of the current system or the system you requested.
Category:
system
Description:
Returns the level of a system.
Example:
[code](sysGetLevel)[/code]
If called in the Charon system will return a 3.
[code](sysGetLevel "SE")[/code]
Returns 1.
Comment:
Useful for seeing the general level of a system. The level of a system determines what level of random stations and random items will appear.
Name:
sysGetName
Syntax:
(sysGetName [string])
Argument List:
[string]: An optional nodeId of the system you want the name from.
Returns:
string: The name of the system.
Category:
system
Description:
Returns the name of the current system if no arguments otherwise returns the name of the system referenced by the string.
Example:
[code](sysGetName)[/code]
If called in St. K's system will return a "St. Katharine's Star".
Comment:
Name:
sysGetNavPathPoint
Syntax:
(sysGetNavPathPoint number spaceObject spaceObject number)
Argument List:
number: The UNID of the sovereign of the point.
spaceObject: One of the two objects to find a point between.
spaceObject: One of the two objects to find a point between.
number: The percent from the first space object to the second space object that you want.
Returns:
vector: A position vector in between the two space objects.
Category:
system, unid
Description:
Finds and returns a point between two space objects.
Example:
Comment:
Useful for finding a position between two space objects.
Name:
sysGetNode
Syntax:
(sysGetNode)
Argument List:
Returns:
string: The name of the node of the current system.
Category:
system
Description:
Returns the name of the node of the current system.
Example:
[code](sysGetNode)[/code]
If called in St. K's system will return a "SK".
Comment:
Very useful for telling where in the network you are.
Name:
sysGetNodes
Syntax:
(sysGetNodes) -> list of nodeIDs
Argument List:
none
Returns:
list of nodeID's
Category:
system
Description:
Returns a list of all the nodes in the game.
Example:
taken from &ssHuaramarca;
[code]
; Pick a random system in Huari space to have a gateway to Huaramarca
(setq gateway
(random
(filter (sysGetNodes) theNode
(and (sysHasAttribute theNode 'ungoverned)
(geq (sysGetLevel theNode) 5))
)))
[/code]
Comment:
Name:
sysGetObjectByName
Syntax:
(sysGetObjectByName spaceObject string)
Argument List:
spaceObject: A space object in the same system as the thing you are looking for.
string: The name of the space object you are looking for.
Returns:
spaceObject: A space object with the given name, if nothing is found returns Nil.
Category:
system, spaceobject
Description:
Finds and returns a space object from a given name.
Example:
Comment:
Useful for finding stations with a given name such as outbound stargates and arena walls.
Name:
sysGetStargateDestinationNode
Syntax:
(sysGetStargateDestinationNode [nodeID] gateID) -> nodeID
Argument List:
nodeID: the node ID (optional. uses current node if not provided)
gateID: the gate ID
Returns:
nodeID: the node ID
Category:
system
Description:
Used to get the nodeID of the node that the stargate connects to.
Example:
taken from stkDistanceToStK
[code]
(block (theDestNode theDist)
(setq theDestNode (sysGetStargateDestinationNode nodeID theGate))
(if (not (find nodesChecked theDestNode))
(block Nil
(setq theDist (stkDistanceToStK theDestNode nodesChecked))
(if (ls theDist bestDist)
(setq bestDist theDist)
)
)
)
)
[/code]
Comment:
Name:
sysGetStargates
Syntax:
(sysGetStargates [nodeID]) -> list of gateIDs
Argument List:
nodeID: the node ID (optional. uses current node if none provided)
Returns:
list of gateIDs
Category:
system
Description:
Used to get stargates in a system
Example:
taken from &dsUseTualiComaDrug;
[code]
; Figure out which gate in the system leads to Huaramarca
(setq gateID (item (filter
(sysGetStargates (sysGetNode)) theGate
(huaIsGateToHuaramarca (sysGetNode) theGate Nil)) 0))
[/code]
Comment:
Name:
sysGlobals
Syntax:
(sysGlobals)
Argument List:
Returns:
list: A list of strings naming all the globals.
Category:
system, function, variable
Description:
Returns a list of all the names of the global functions and global variables.
Example:
Comment:
Not useful for general use but useful for finding the names of all the functions.
Name:
sysHasAttribute
Syntax:
(sysHasAttribute [nodeID] attrib) -> True/Nil
Argument List:
nodeID: the node ID of the star system
attrib: the attribute to look for in the system
Returns:
boolean: true/nil depending upon success
Category:
system
Description:
Used to look for criteria in star systems.
Example:
taken from &ssHuaramarca;
[code]
; Pick a random system in Huari space to have a gateway to Huaramarca
(setq gateway
(random
(filter (sysGetNodes) theNode
(and (sysHasAttribute theNode 'ungoverned)
(geq (sysGetLevel theNode) 5))
)
)
)
[/code]
Comment:
Name:
sysPlaySound
Syntax:
(sysPlaySound unid [sourceObj]) -> True/Nil
Argument List:
Unid: the unid of the sound
[sourceObj]: where the sound comes from
Returns:
boolean: True/ Nil depending upon success
Category:
system, music
Description:
Not used in Transcendence.tdb
Mods can use this function to vary music and can be used to great effect.
Example:
Comment:
Name:
sysPoolUsage
Syntax:
(sysPoolUsage)
Argument List:
Returns:
list: A list of numbers representing how much resources the game is using.
Category:
system
Description:
Returns a list of numbers representing how much resources the game is using.
Example:
Comment:
Not useful for general use at all.
Name:
sysSetData
Syntax:
(sysSetData [string] string expression)
Argument List:
string: The optional name of the system node. If not there uses the current system.
string: The name of the data.
expression: The data you want to store.
Returns:
condition: True if successful, Nil otherwise.
Category:
system, data
Description:
Sets the named data in the given system to the expression.
Example:
[code](sysSetData "power" 9001)[/code]
Stores the number 9001 in the power data for the current system.
Comment:
Useful for getting/storing information about a system such as how many times the player has visited the system.
Name:
sysStartTime
Syntax:
(sysStartTime) -> True/Nil
Argument List:
None
Returns:
Boolean: true/nil
Category:
system
Description:
Used to start time again (after it has been stopped permanently by sysStopTime)
Example:
Comment:
Name:
sysStopTime
Syntax:
(sysStopTime number spaceObject)
Argument List:
number: How many ticks you want to stop time for.
spaceObject: A space object that you want immune from the time stop. Can be any spaceobject. (can not be Nil)
Returns:
condition: True if successful, Nil otherwise.
Category:
time, system
Description:
Stops time for the game except for the given spaceObject.
Please not that the function stops time for any timers, even if placed on the spaceObject that you want to be immune.
-1 stops time permanently
Example:
[code](sysStopTime 500 gplayership)[/code]
Stops time for everything except for the player.
Comment:
Used with the Gem of Contrition.
Name:
sysTicks
Syntax:
(sysTicks)
Argument List:
Returns:
number: A timer from your computer.
Category:
system, time
Description:
Returns the current time from your computer in ticks.
Example:
Comment:
Use unvGetTick, sysTicks may not be synchronized with Transcendence ticks.
Name:
sysVectorAdd
Syntax:
(sysVectorAdd vector vector)
Argument List:
vector: first vector to add
vector: second vector to add
Returns:
vector: the sum of the 2 vectors
Category:
vector operator, system
Description:
Function used to sum 2 vectors.
Example:
Comment:
Basic function for summing 2 vectors
Name:
sysVectorAngle
Syntax:
(sysVectorAngle vector)
Argument List:
vector: The vector you want to find the angle of with respect to the origin of the system.
Returns:
number: The angle in degrees with respect to the origin of the system.
Category:
vector operator, 0.99
Description:
Finds and returns the angle of the given vector.
Example:
[code](sysVectorAngle (objGetPos gplayership))[/code]
Returns the angle of the player ship with respect to the origin of the system.
Comment:
Basic vector function.
Name:
sysVectorDistance
Syntax:
(sysVectorDistance vector vector)
Argument List:
vector: the first vector
vector: the second vector for calculating the distance
Returns:
number: distance between the 2 vectors in light-seconds
Category:
vector operator, system
Description:
This function calculates the distance from two given positions (vectors)
Example:
Comment:
Basic vector operator function
Name:
sysVectorDivide
Syntax:
(sysVectorDivide vector number)
Argument List:
vector: the vector you want to be divided by
number: the integer that divide the vector
Returns:
vector: the resulting position after the division
Category:
vector operator, system
Description:
This function returns a position (vector) after dividing the submitted vector by the integer
Example:
Comment:
Basic vector operator function
Name:
sysVectorMultiply
Syntax:
(sysVectorMultiply vector number)
Argument List:
vector: the vector you want to be multiplied
number: the integer that multiply the vector
Returns:
vector: the new position after the multiplication
Category:
vector operator, system
Description:
This function returns a position (vector) after multipling the submitted vector by the integer
Example:
Comment:
Basic vector operator function
Name:
sysVectorPolarOffset
Syntax:
(sysVectorPolarOffset vector number number)
Argument List:
vector: The origin of the new vector. Same as the systems origin if Nil.
number: The angle of the vector from 0 to 360. 0 is to the right.
number: The length of the vector in light seconds.
Returns:
vector: A new vector based on the origin and polar coordinates given.
Category:
vector operator, system
Description:
Makes a vector from the given origin and polar coordinates.
Example:
[code](sysVectorPolarOffset gplayership 0 10)[/code]
Returns a vector that points to a position 10 light seconds to the right of the player.
Comment:
Essential if you want to use vectors of a certain length or direction.
Name:
sysVectorPolarVelocity
Syntax:
(sysVectorPolarVelocity number number)
Argument List:
number- the angle of the vector
number- the speed of the vector (in % of c)
Returns:
velVector- returns the new velocity vector
Category:
vector operator, system
Description:
A useful wrapper function for other velocity operator functions that require messy velVector arguments.
Example:
(objSetVel gPlayerShip (sysVectorPolarVelocity (shpGetDirection gPlayerShip) 50))
Will cause the playership to scream forward at 50% lightspeed.
Comment:
A necessary function if you are using objIncVel or objSetVel which take velVectors as their velocity arguments.
Name:
sysVectorRandom
Syntax:
(sysVectorRandom origin radius separation criteria)
Argument List:
vector: The origin of the new vector. Same as the systems origin if Nil.
number: The radius in ls away from the origin.
number: The minimum separation in light-seconds away from any spaceObject that matches 'filter' criteria. If criteria is Nil, then we avoid all objects.
criteria: A filter. See sysFindObject for the list of criteria.
Returns:
vector: A new random vector that matches the parameters used.
Category:
vector operator, system
Description:
(sysVectorRandom) is designed to find a spot that is not near anything.
Example:
Comment:
Useful if you want a random vector with a filter.
Name:
sysVectorSpeed
Syntax:
(sysVectorSpeed velVector)
Argument List:
velVector - a velocity vector
Returns:
number - an integer representing a speed (in % of c)
Category:
vector operator, system
Description:
A very useful function to transform messy velVectors into human readable speeds.
Example:
(sysVectorSpeed (objGetVel gPlayerShip))
Returns the speed the playership is travelling at (in % of c)
Comment:
Another useful wrapper function when dealing with velVectors.
Name:
sysVectorSubtract
Syntax:
(sysVectorSubtract vector vector)
Argument List:
vector: the first vector to be subtracted
vector: the subtracting vector
Returns:
vector: resulting position after the subtraction.
Category:
vector operator, system
Description:
This function returns a position (vector) from a subtraction of the two given vectors.
Example:
Comment:
Basic vector operator function
Name:
typCreate
Syntax:
(typCreate unid XML) -> True/Nil
Argument List:
unid: a valid unid. Is usually created with typDynamicUNID.
XML: XML to feed into TypCreate. Can be created with cat strings + subst or fed straight in (look at Beyond the Mainline).
Returns:
True: if TypCreate works properly it returns true
Nil: if Typcreate fails for some reason it returns nil
Category:
1.08, type, unid
Description:
Used to create new types ingame. Can be anything from topology to items to stations to playerships, etc.
Example:
http://forums.kronosaur.com/viewtopic.php?f=5&t=4843
Comment:
Best function in the game, hands down. Lets you create stuff on the fly and new types. Someone needs to make a mod that abuses this to the fullest extent.
Name:
typFind
Syntax:
(typFind criteria) => (list of unids)
Argument List:
Criteria: a string describing what structures you want to find (see below)
Returns:
list of UNID's
Category:
type, unid, 1.0
Description:
This function allow you to return a list of all the xml structures defined in Transcendence.
Example:
(typFind "s +baseClass") -> (&scStdAutonBase; &scStdWingmanBase;)
Comment:
* = all types
$ = currency UNID
a = an adventureDesc UNID
b = item table UNID
c = effect type UNID
d = dock screen UNID
e = space environment UNID
f = overlay UNID (apparently original name was 'energy field')
g = globals UNID (currently returns nothing?)
h = ship table UNID
i = item type UNID
m = image UNID
n = system node UNID (currently returns nothing?)
p = power UNID
q = system table UNID
s = ship class UNID
t = station type UNID
u = sound UNID (currently returns nothing?)
v = sovereign UNID
w = name generator UNID (currently returns nothing?)
y = system type UNID
z = system map UNID
_ = template type UNID // We don't support enumerating template types (TSE/CDesignType.cpp)
V = Include Virtual types
+isPlayerClass:true/false = filters in/out ship classes with playersettings
+unid:[a unid] = returns the requested unid if extant, or nil
Name:
typFireObjEvent
Syntax:
(typFireObjEvent type obj string)
Argument List:
type: the unid of the type that holds the event
obj: the target of the event
string: the name of the event
Returns:
True/Nil
Category:
spaceobject, type, event
Description:
Useful function for firing events without having to create the object that contains the event.
Example:
(typFireObjEvent &baStdWingmanBase; gSource "OnCreate") returns True (assuming gSource is a valid obj)
Comment:
Name:
typGetDataField
Syntax:
(typGetDataField unid field) -> data
Argument List:
UNID: unid of of the type to get data from
field: the data to be found
Returns:
data: whatever is in the data field
Category:
type
Description:
Used to get data like fireAccuracy,
fireRangeAdj, etc.
Example:
Comment:
List of data tags can be found here: http://wiki.neurohack.com/transcendence/wiki/modding/function/legend#data_fields
Name:
typGetGlobalData
Syntax:
(typGetGlobalData UNID key) -> value
Argument List:
UNID: The UNID of the type you want to get the data from.
key: The name of the data you want to get.
Returns:
value: The data named by the string for the given type. Returns Nil if there is no data as named by the string.
Category:
type, data, 0.99, unid
Description:
Returns the named global data of the given type.
Example:
[code](typGetGlobalData &itSolarPanelArray; "rincost")[/code]
Returns the data that is in the "rincost" global in the itSolarPanelArray.
Comment:
Very useful for getting data from design types.
The design types are
ItemType, Shipclass, StationType, Image, Sovereign, DockScreen, EncounterTable, Effect, Sound,ItemTable, and SystemType.
Name:
typGetStaticData
Syntax:
(typGetStaticData number string)
Argument List:
number: The UNID of the type you want to get the data from.
string: The name of the data you want to get.
Returns:
The data named by the string for the given type. Returns Nil if there is no data as named by the string.
Category:
type, data, 0.99, unid
Description:
Returns the named static data of the given type.
Example:
[code](typGetStaticData &itSolarPanelArray; "rincost")[/code]
Returns the data that is in the "rincost" static data in the itSolarPanelArray type.
Comment:
Very useful for getting data from design types.
The design types are
ItemType, Shipclass, StationType, Image, Sovereign, DockScreen, EncounterTable, Effect, Sound,ItemTable, and SystemType.
Name:
typHasAttribute
Syntax:
(typHasAttribute unid attrib) -> True/Nil
Argument List:
UNID: a unid of any type that has attributes.
attribute: the attribute to look for
Returns:
boolean: true/nil depending upon success
Category:
type
Description:
Used to look for whatever is in the attributes= "etc etc" for whatever the UNID points to.
Example:
Comment:
Name:
typIncGlobalData
Syntax:
(typIncGlobalData number string [number])
Argument List:
number: The UNID of the type you want to increment the data in.
string: The name of the data you want to increment.
number: The optional number that gets added to the data.
Returns:
number: The value of the data after it has been incremented.
Category:
math, data, 0.99, unid
Description:
Increments the data in the type by the given number (if no number is given it increment it by one).
Example:
[code](typIncGlobalData &itSolarPanelArray; "rincost" 100)[/code]
Returns the rincost in itSolarPanelArray plus 100, if it didn't exist before it creates it and sets it to 100.
Comment:
Basically a helper function so you don't have to do set and add all the time.
Name:
typSetGlobalData
Syntax:
(typSetGlobalData UNID key value)
Argument List:
UNID: The UNID of the type you want to set the data of.
key: The name of the data you want to set.
value: The value that the data will be.
Returns:
True if successful.
Category:
unid, type, data, 0.99
Description:
Sets the data in the given design type to the passed in data.
Example:
[code](typSetGlobalData &itSolarPanelArray; "rincost" 100)[/code]
Sets the rincost global data in itSolarPanelArray to 100.
Comment:
Very useful for setting data in design types.
The design types are
ItemType, Shipclass, StationType, Image, Sovereign, DockScreen, EncounterTable, Effect, Sound,ItemTable, and SystemType.
Name:
uiCanPlayMusic
Syntax:
(uiCanPlayMusic filename)
Argument List:
filename: the music file to play
Returns:
Boolean: True/Nil
Category:
ui, system, music
Description:
Not used in mods yet, but is a very promising function allowing for atmospheric music to be played.
Example:
Not found in Transcendence.tdb
Comment:
Name:
uiGetMusicCatalog
Syntax:
(uiGetMusicCatalog) ->
Argument List:
None
Returns:
list of files
Category:
music, ui
Description:
Gets a list of files
Example:
Not used in Transcendence,tdb
Comment:
What kind of list is being returned? Does this mean we don't need to specify a sound resource using a UNID anymore?
Name:
uiGetMusicState
Syntax:
(uiGetMusicState) -> ('playing filename position length)
Argument List:
None
Returns:
('playing filename position length)
Category:
ui, music
Description:
Used to find out how long music has been playing.
Example:
Comment:
Name:
uiPlayMusic
Syntax:
(uiPlayMusic filename [pos])
Argument List:
filename: the file in question
pos: Unsure. The position of the music in respect to how long it's been playing?
Returns:
boolean:True/Nil
Category:
music, ui
Description:
Used to play music.
Example:
Not used in Transcendence.tdb
Comment:
Name:
uiStopMusic
Syntax:
(uiStopMusic)
Argument List:
None
Returns:
Unsure
Category:
ui, music
Description:
Used to stop music playing
Example:
Not used in transcendence.tdb
Comment:
Name:
unvGetRealDate
Syntax:
(unvGetRealDate)
Argument List:
None
Returns:
list: Year month day
Category:
time
Description:
Used in St. Kat's to generate the appropriate fruits.
Example:
(dbglog(unvGetRealDate)))
returns
(2012 6 1)
on June 1st, 2012.
Comment:
Name:
unvGetRealDate
Syntax:
(unvGetRealDate) -> (year month day) GMT
Argument List:
none
Returns:
(year month day) GMT
Category:
time
Description:
Used to get the calandar date.
Example:
taken from &stStKatsArcology;
[code]
; Figure out which to produce based on the real
; calendar
(setq theMonth (item (unvGetRealDate) 1))
(switch
(leq theMonth 3)
(setq theItemUNID &itIncandescentLucuma;)
(leq theMonth 6)
(setq theItemUNID &itIncandescentPeaches;)
(leq theMonth 9)
(setq theItemUNID &itIncandescentStrawberries;)
(setq theItemUNID &itIncandescentBellFruit;)
)
[/code]
Comment:
A mod could use this to trigger events on certain days.
Name:
unvGetTick
Syntax:
(unvGetTick)
Argument List:
Returns:
number: The number of ticks since the game has started.
Category:
time
Description:
Returns how many ticks since that game was loaded.
Example:
[code](unvGetTick)[/code]
This will return how many ticks since the game.
Comment:
Useful for telling how long between two functions have been run.
Name:
unvUNID
Syntax:
(unvUNID string)
Argument List:
string: Part of the name of the item or ship you want.
Returns:
list: A list that has a random item or ship that matches part of the name. The list looks like if a ship (UNID 'shipclass name) and if a item (UNID 'itemtype name)
Category:
random, system, unid
Description:
Finds a random ship or item that matches the name you passed in. Returns its UNID in a list with some other information.
Example:
Comment:
Like itmCreateByName but with both ships and items. It doesn't create the ship or item.