Fallout Modding 4: Script (IPP) files

[Temaperacl]

I'll keep working on this when I get the time, here's what I have typed up so far:


Basic syntax:
Most of my work so far has been done on people so some information will be missing for map and item scripts, I'm sure.
(Note: Pretty much all commands except 'if .. then', should be terminated by semi-colons. I've tried to indicate this where appropriate, but I may have missed some [note also that Var and begin are correctly not terminated by semicolons.]).

Script Files
A script file has the form:

script ScriptName('ScriptName');
uses ScriptLibs;
VarBlock
ProcedureList
Procedures

begin
end.

(Yes, that final end is terminated by a period.)
ScriptName- I haven't messed around with this much- having it the same as the int and msg file names works fine (acklint for the script acklint.ipp that uses acklint.msg for example.

ScriptLibs- Again, one I haven't messed around with much- basically the list of the lib files to use. This is just a comma-delimited list of other ipp files (minus the ipp extension). (The basic ones which you'll need to include are "system,stdlib").
VarBlock - A list of the variables for the script- explained later.

ProcedureList- An optional list of the procedures in the script file in the format procedure ProcedureName;forward;. there is no problem with not including this.

Procedures- The procedures that are contained in this script file. (Explained below).

Procedures
Pretty much all code is stored in procedures. These have the format

procedure ProcedureName;
VarBlock
CodeBlock

CodeBlock - This is the block of code (explained later) that is contained in that procedure.

VarBlock - This is the block of vars (explained later) that is limited to that procedure.

ProcedureName - This is the name of the procedure. In general, this can be whatever you like (no spaces), with two warnings-
1) I'd bet you things will go wrong if you name it the same as another function. I haven't actually tried it, but if you are in this situation, you are probably doing something wrong.
2) There are certain functions that will be called for certain purposes in the game. These (the ones I know about anyhow) are:

talk_p_proc - Called when the person is talked to. More details on dialogue are available in the Fallout Modding 2: Dialogue thread.

destroy_p_proc - Called when the person is destroyed (killed).

look_at_p_proc - Called when the person is looked at (when you rest the mouse over the person- this is where you would show the basic description).

description_p_proc - This is called when the person is examined (here you would show the detailed description).

use_skill_on_p_proc - Called when a skill is used on the person. You can find out what skill was used with UseSkill (described later).

damage_p_proc - Called when the person is dealt damage.

map_enter_p_proc - Called when the player enters the map.

critter_p_proc - Called all the time (If the person wanders, for example, it would be coded in here.

pickup_p_proc - Called when someone is caught placing or taking an item from the person (using steal).

combat_p_proc - Called during the person's turn during combat. (The only script I've seen it in is the Overseer's in order to (I believe) give him unlimited ammo.).

CodeBlocks
A code block is a group of commands and functions surrounded by begin and end;. Thus, the following is a CodeBlock:

begin
writeln(GetStr(_script_,110);
writeln(GetStr(_script_,112);
writeln(GetStr(_script_,114);
end;

as is

begin
end;

VarBlocks
This is simply a list of the variables that will be usable within a given scope. A VarBlock at the start of the script file will be global variables. VarBlocks between a function name and the CodeBlock for the function will be limited to that function. VarBlocks have the form:

Var
ListOfVars

List of vars is a list of the variable names. (Example:

Var
s;
medium;
LongVariableName;

)

Commands
Assignment
:= is used to assign a value to another (x:=2; for example).
= is 'is equal to' for comparisons (if x=2 then for example).
> is 'is greater than' for comparisons
< is 'is less than' for comparisons.
>= is 'is greater than or equal to' for comparisons.
<= is 'is less than or equal to' for comparisons.
<> is 'is not equal to' for comparisons.
+ is used for addition.
- is used for subtraction.
* is used for multiplication.
/ is used for division.
' is used to surround strings (Editorial Comment: *Slamming head against brick wall for not noticing this sooner.*)
@ address of (I think) (Used when you need to pass a function (the function, not the results of the function) to another function (mainly 'answer').
if:
This is used to create conditional statements. the syntax is

if Condition then
CodeBlock

Condition should be true or false (false=0, true= not 0). If it is true, the block is executed. Comparisons (=,<,<>,etc.) will return 1 if they are true- false otherwise.

(example:

if x>2 then
begin
...
end;

will execute if x is greater than 2.
GetStr(353,top_msg-1)<>''
Functions
Functions are used for the majority of the work in the script, and must be defined (most of them are defined in stdlib.ipp. For those that aren't defined there, I'll provide the code you have to insert into stdlib.ipp in order for them to work (after I get most or all of them in, I'll probably provide a file that will have all the code in one spot). Unless otherwise specified, these can be inserted anywhere you would use a number and it will use the return value. (for example if GetStr(_Script_,102)='' then).

Note: When a script/.msg file number is required, you can use _script_ to refer to the current script and associated .msg file.

Self
This is used to indicate the person who is running the script (so, for example, Self in klint's script would refer to klint. )

Player
This is used to indicate the player.

Sender
This is used to indicate who triggered the script. (For example, if Sender=Player then would test to see if the person who triggered the event was the player)

writeln(str)
Outputs a string to the message window (on the bottom left of the screen).
str - this is a string to output. This can either be a string bounded by '' or a string retrieved with other functions.

GetStr(scrnum,strnum)
Returns a string from a file.
scrnum- the .msg file number to get the string from.
strnum- the number of the string to get (this will be the first number in the line in the msg file (Example, for {102}{}{This is a string}, the number would be 102 for the string 'This is a string'.).

SayForAnswer(scrnum,str)
Displays dialogue. Should be followed by Answers.
scrnum- the .msg file number to get the string from.
str- the string to display- either a '' string, or the number of the string to get from the msg file.

SayWOAnswer(scrnum,str,parm1)
Displays dialogue that a response is not expected to.
scrnum- the .msg file number to get the string from.
str- the string to display- either a '' string, or the number of the string to get from the msg file.
parm1- Not sure. Might be used with Empathy..


Answer(int,scrnum,str,funcnum,parm1)
Used to display a user-choosable answer.
int- the min intelligence to be able to choose this answer. A range of 7 can use the answer (Thus, with a value of '2', chars with INT 2-8 could choose that answer). The commonly used values are:
-3 - for Low-INT chars
4 - for average and above
7 or 8 - for high-INT chars.

DebugPrint(msg)
Should print a message out to the Debug window (or maybe to the normal message window, but when you are in debug mode?) - I haven't been able to get into debug mode, so I can't be sure- if anybody knows how, let me know, please.

See(who,whom)
This returns true or false determining if who can see whom
who- the person who will be doing the seeing.
whom- the person who might be seen.
(Example: 'if See(Self,Player) then' will do the code in the if statement if the person who's script it is can see the player.)

GetStat(obj,stat)
Returns the value of a stat.
obj- the person/object to get the stat from.
stat- the stat to get the value of. Known numbers are (If/when you get more, please let us know since I haven't gotten around to testing (other) numbers to see what they refer to yet):
0 - Strength
1 - Perception
2 - Endurance
3 - Charisma
4 - Intelligencee
5 - Agility
6 - Luck
34- Gender (0=male, 1=female)

PlayerHasSexAppealTrait
Return 1 (true) if player has the Sex Appeal trait, false (0) otherwise.

PlayerHasPresencePerk
Return 1 (true) if player has the Presence trait, false (0) otherwise.

Month
Returns the current month:
1 - Jan
2 - Feb
3 - Mar
4 - Apr
5 - May
6 - Jun
7 - Jul
8 - Aug
9 - Sep
10- Oct
11- Nov
12- Dec

TimeOfDay
This is the current time. For example, at 3am, it will return 300, at 4:14 pm, it will return 1614.

SetLight(p1)
Sets the current light level. 100 is full brightness, 40 seems to be used for darkest night value.

GetSkill(obj,skillnum)
Get the value of a skill.
obj- person to get the skill value from.
skillnum- skill to get value of:
0 -Small Guns
1 -Big Guns
2 -Energy Weapons
3 -Unarmed
4 -Melee Weapons
5 -Throwing
6 -First Aid
7 -Doctor
8 -Sneak
9 -Lockpick
10-Steal
11-Traps
12-Science
13-Repair
14-Speech
15-Barter
16-Gambling
17-Outdoorsman

(UsedSkill at bottom of page)

Not Gotten To - you can ignore this
I'm going through the stdlib provided with the compiler, and then I'll go through the functions you need that aren't in the stdlib but that you may run across in a decompiled script. I'm just putting these here so I know which of the functions in the stdlib I haven't gotten through yet. As long as there is a list under here, you know I haven't gotten through writing up all the stdlib functions yet.

GetName(obj)
FrameID(obj)
Misc(parm1,parm2)
OpenDialog(scr,obj,parm1,parm2,parm3)
CloseDialog
Attack(who)
SetBattleParm(obj,parm1,parm2,parm3)
GetItemCountByXY(xy,level,objectid)
GetItemAddressByXY
Friend(critterid)
SetXY(obj,xy,level)
DistanceObj(parm1,param2)
CreateObj(p4,p3,p2,p1)
GiveItems(p3,p2,p1)
RetN(p1)
SetPlayerPos(p4,p3,p2,p1)
GetPerk(p4,p3,p2)
TotalTime
AddExp(XP)
Say(obj,strnum,color)

Non StdLib
This isn't a stdlib function, but I made reference to it earlier, so I should post it here:

UsedSkill
Used to determine what skill triggered a call to use_skill_on_p_proc
The code you need to insert for this is:

function UsedSkill;inline;
begin int 80fa end; end;

[Red]

First of all, nice work, it's about time someone bothered to create some docs in English...

ScriptName- I haven't messed around with this much- having it the same as the int and msg file names works fine (acklint for the script acklint.ipp that uses acklint.msg for example.

Basically, this is used for 2 things I've found. First, it names the output file (ie: rename acklint.ipp to hello.ipp, compile it and you should still get acklint.int), second (and this I'm certain about), this makes the compiler check on which line acklint is referenced to in scripts.lst and thus allows you to use the _script_ identifyer.

ScriptLibs- Again, one I haven't messed around with much- basically the list of the lib files to use. This is just a comma-delimited list of other ipp files (minus the ipp extension). (The basic ones which you'll need to include are "system,stdlib").

Note that stlib includes everything that's needed to create a "new" empty script. This means that given you toy with decompiled script, you'll usually need to remove stdlib altogether. I've found that some stuff was still left in system which should of gone into stdlib.

VarBlock - This is the block of vars (explained later) that is limited to that procedure.

[...]

VarBlocks
This is simply a list of the variables that will be usable within a given scope. A VarBlock at the start of the script file will be global variables. VarBlocks between a function name and the CodeBlock for the function will be limited to that function. VarBlocks have the form:

Var
ListOfVars

List of vars is a list of the variable names. (Example:

Var
s;
medium;
LongVariableName;

)

This is true, however I'd like to point out that the compiler doesn't process this properly, as instead of creating a local variable for the function, it creates a global one. This means that every time you create a new variable it needs to have a unique name even though others are not within the scope of the function... This is quite annoying, especially dealing with decompiled scripts which use local variables.

/ is used for division.

There is also \. I actually have no idea of the difference, usually in Pascal one of them is used for float divisions, and the other for integer divisions... but FO never uses floats (although it might for calculations...)

' is used to surround strings (Editorial Comment: *Slamming head against brick wall for not noticing this sooner.*)

Um... OK...

@ address of (I think) (Used when you need to pass a function (the function, not the results of the function) to another function (mainly 'answer').

Yeah... means "address of (function)" I don't think it can be used in any other context even though it could be under Pascal.

You're also missing stuff like "&" which is a bitwise AND, and | which is a bitwise OR. I can explain further for those which might not know what this is... And of course normal ANDs, ORs and NOTs.

GetStr(353,top_msg-1)<>''

What's that doing there?

(after I get most or all of them in, I'll probably provide a file that will have all the code in one spot).

I suggest leaving all the code in 2 files as it is, as when doing a "custom" script, you'd use the 2 files, while when modifying a decompiled script, you'd only use stdlib

Unless otherwise specified, these can be inserted anywhere you would use a number and it will use the return value. (for example if GetStr(_Script_,102)='' then).

I'd just like to give afew examples where this isn't used: Doors, locks, safes. They (usually) use the generic.msg file (which interestingly enough has not an .ipp file, yet is still listed in scripts.lst). Another example is the usually "Player gain XX XP" which is taken from generic.msg again...

Answer(int,scrnum,str,funcnum,parm1)
Used to display a user-choosable answer.
int- the min intelligence to be able to choose this answer. A range of 7 can use the answer (Thus, with a value of '2', chars with INT 2-8 could choose that answer). The commonly used values are:
-3 - for Low-INT chars
4 - for average and above
7 or 8 - for high-INT chars.

Int:
When Int is positive (1 to 10), then this means "player has Int or equal", so 4 means that the player requires 4 int or more to see this answer option.
When Int is negative (-1 to -9), this means that the player needs ot have less or equal. So -3 means "player has 3 of Int or less"
Parm1:
This is with the Empathy Perk. 50 = Normal reaction, 51 = "NPC will like", 49 = "NPC will not like". This actually only has 2 effects: the colour highlight of the text before enterting a node, and the change of attitude if the NPC is a talking head. Given this had more of an effect (ie piss the people off), then it would of been refered and modifyable through an SVAR[], which it seems not to do, as otherwise Lynette would of used that to determine if you pissed her off... But then again maybe the programmer who did Lynnette didn't know you could of done it, so that's still nto really necesserely true.. Hargh...

DebugPrint(msg)
Should print a message out to the Debug window (or maybe to the normal message window, but when you are in debug mode?) - I haven't been able to get into debug mode, so I can't be sure- if anybody knows how, let me know, please.

I remember (or think I remember) seeing a patch somewhere where "it enabled the programmer's debug messages". However I don't know if I just imaged it, or it was for another game altogether... Doh. I looked on the net and never found any reference. This could be DAMN useful for scripting...

GetStat(obj,stat)

I'm quite sure 35 = Current HP

combat_p_proc:
This happens at the end of a turn. It's also used by the Geckos to inflict radiation damanfe to the player for example.

Other functions:
Misc(14,0):
Not quite sure, but it has something to do with entering the map since that's always where you find it...

Misc(16,0):
Number of NPC's following you

Misc(17,Town):
Is Town on your Pipboy. To find a list of the cities, open text/english/game/map.msg, in the {1500}. Of course remove 1500 for the number reference. - Another table is in data/city.txt (see CurrentLocation below).
To make things easyer, here's the list:

0 - Arroyo
1 - Den
2 - Klamath
3 - Modoc
4 - Vault City
5 - Gecko
6 - Broken Hills
7 - New Reno
8 - Sierra Army Depot
9 - Vault 15
10 - New California Republic
11 - Vault 13
12 - Military Base
13 - Redding
14 - San Francisco
15 - Navarro
16 - The Enclave
17 to 19: deprecated maps...
20 - Ghost Farm
21 - Car Outta Power
22 - Arroyo (dead)
23 - Toxic Caves
24 - Den Slave Run (Not really used)
25 - Raiders
26 to 44: Used by random encounters
45 - Vault 13 (The fake one, befor eyou enter it)
46 - Fake Vault 13 (Once you entered 45...)
48 - Stables

Misc(18,Entity):
Wether Sender is in the "Light" in relation to Entity.

Misc(19,25):
? 'trap door'

Misc(22,0):
Have you entered this map from the "Town map".

Misc(30,0):
Town (see Misc(17,Town) table...) in which the car is.

Misc(40,Skill):
Unkown. Another UsedSkill?
Maybe it does a test between Self and Sender to see wether Sender has a better value with that skill?

Misc(44,0):
X location on world map.

Misc(45,0):
Y Location on world map.

Misc(46,0):
Current town (See CurrentLocation)

Misc(47,0):
Checks the player sex. Not sure if it compares with Self.

Misc(49,Entity):
I beleive this is used for entities, to check if you can break doors by damaging them (otherwise they're invincible like the enclave doors). If 6 then it would mean the door is not invincible...

Misc(51,Entity):
Entity is an entity in the game - usually Self.
Return's the status of the entity:
2 = Dead.
Sorry, that's all I suspect...

CurrentLocation:
Current location of Player - See data/city.txt for location/area list.

Well, that's all for now.

[Red]

Misc(40,Skill):
I figured this one out. This checks wether you tagged a skill.

[Red]

GetPerk(0, Entity, Perk):
Gets the perk from the Perk list, See text\english\game\perk.msg.
Note that this index starts at 1 instead of 0, so 0 is actually Awareness... (ie: Perk is perk.msg - 1).

GetPerk(2, Entity, Trait):
Gets if the player has a trait. No funky -1 crap here.

GetPerk(1, Entity, Parm):
This one is weird, I still don't get it, but I beleive it's internall variables indentifying the state of the entity.
666 seems to be wether the entity is hostile to the player
6 seems to be the group with which the entity is "Associated".

SetBattleParam(Parm1, Entity, Parm2, Parm3):
Basically this should be called SetPerk I guess.
Parm1 is the same as the GetPerk variations, Parm2 is the same as Parm in GetPerks, and Parm3 is the value to which you want it set.

[Rat Keeng]

Misc(40,Skill):
I figured this one out. This checks wether you tagged a skill.

Tested true, theoretically and practically


Thanks for all the info both of you.

[Red]

Misc(40,Skill):
Tested true, theoretically and practically

The funny thing about this is that I was making that list for here, posted it, then hoped on the BIS boards and *POOF*, even though I dind't know what Misc(40,-) was, my mind just figured that one out when reading that post about tagged skills tirggering stuff... I checked his script, and low and behold it used exacly that line.

Well, Rat Keeng knows what I'm talking about

[Tank]

I am soo lost now...

[ABel]

I remember (or think I remember) seeing a patch somewhere where "it enabled the programmer's debug messages". However I don't know if I just imaged it, or it was for another game altogether... Doh. I looked on the net and never found any reference. This could be DAMN useful for scripting...

This debugging patch hides here: http://members.fortunecity.com/noid84/patch.html

[Rat Keeng]

I remember (or think I remember) seeing a patch somewhere where "it enabled the programmer's debug messages". However I don't know if I just imaged it, or it was for another game altogether... Doh. I looked on the net and never found any reference. This could be DAMN useful for scripting...

This debugging patch hides here: http://members.fortunecity.com/noid84/patch.html

It works! Woohoo!

Thanks alot.

[Red]

Yeah, i works dandee (on WinXP anyhow).
I set it up so it pipes to debug.log, and then use the unix utility "tail" with the -f option, and slap my DOS console onto my second monitor.

This way I have the debug window on my second monitor instead of having to quit to read it - or it taking 3/4 of the damn screen...

[Temaperacl]

I am soo lost now...

You know C(++), right? Just think of it this way:

begin is {
end; is }
:= is =
= is ==
<> is !=

and if statements require a "then" afterwards.

Most of the rest of the discussion is of the functions that are available.. That help any?


Red:
Thanks for the corrections and additions- if you don't mind, when all the information is down, I'll combine it all into one document for easier reference.

I suggest leaving all the code in 2 files as it is, as when doing a "custom" script, you'd use the 2 files, while when modifying a decompiled script, you'd only use stdlib

What decompiler are you using? The one I have draws the definitions from a .mdb (I think) file, which includes many definitions not in the stdlib provided with the compiler I use..



ABel:
Great- thanks! I'll test it on my machine as soon as I get home.

[Red]

well, all the function definitions should be left in a single file (in system, put all the "int" stuff), while leaving all the forward function definitions and the variables in stdlib - although the forward declaration seems to be almost pointless to the compiler as you seemed to have mention - if so then you could fit it in system for reference.

The point was basically to allow the less modifications to the int script right after being decompiled.

BTW do you happen to know if it supports comments? As that would come in quite handy

[ABel]

What about making some sort of site, where such information could be collected and systemized? (I just do not think, that the message board is reliable enough to store all the documentation here ). Such site would be really useful for all the modders.
There were some bugs in the original stdlib.ipp, and a lot of new opcodes were explored and added by TeamX, so why not to share this info?

About comments: if you are talking about ipp.exe compiler, it suports Pascal-like comments, both (* ... *), and { ... }.

[Kreegle]

Once we've got the template finished, I can hand that over to someone and they can update all of the modding info, then upload it here - if you want.

[Red]

Hey ABel, do you guys still have the source of the decompiler? As there's a few opcodes which simply can't be added to it... Mainly ones which trigger the "begin ... end;" statements...
Well, I might be wrong as it might be simply adding the proper opcodes to the db which would make it work, however I don't quite understand russian so it's hard to understand the docs...

As for a site, well, isn't that other site about all modding (the one in the other thread which keeps on saying we're falming him) a prime candidate for storing this information?

[ABel]

Hey ABel, do you guys still have the source of the decompiler? As there's a few opcodes which simply can't be added to it... Mainly ones which trigger the "begin ... end;" statements...
Well, I might be wrong as it might be simply adding the proper opcodes to the db which would make it work, however I don't quite understand russian so it's hard to understand the docs...

Yes, the sources are still here. But what are those opcodes?

As for a site, well, isn't that other site about all modding (the one in the other thread which keeps on saying we're falming him) a prime candidate for storing this information?

I was thinking about some kind of interactive knowledge base, where everyone can contribute new information. But I have no idea how to make it comfortable to use.

[Red]

80c7 mainly I stil don't grasp how it works, but it looks like a switch statement... There was another one, but I don't recall it nor where to find it - and for all I remember it might of been the same...

Couldn't you share with us the new stuff?

[ABel]

80c7 mainly I stil don't grasp how it works, but it looks like a switch statement...

This one is called script_action. I do not know its functions, only the name.

Couldn't you share with us the new stuff?

Sure. Here: http://return0.pisem.net/Opcodes/deco&ipp_29.05.rar is the latest decompiler base and stdlib.ipp.
And here is little table with names and entry points of some opcodes: http://return0.pisem.net/Opcodes/mixed.txt

[Red]

First of all, thanks a bunch,

second, i just remembered something... the local variables are global...
This poses a problem when declaring twice the same named local variables...

[Red]

Abel:
If you could add to the DB this stuff:

Code: Select all

[+] 801b	Unknown801B(p2,p1)
[+] 8027	Unknown8027(p3,p2,p1)
[*] 8044	ABS -> Floor (Very different...)
[+] 804d	Fo1DialogEnd
[+] 804e	Fo1DialogStart
[+] 8052	Fo1DialogReply(p2,p1)
[+] 8054	Fo1Message(p2,p1)
[*] 8061	sayMsgTimeout -> SayMsgTimeout
[+] 80cd	AnimateStandObj2(p1)

[+] 80e5	SetAreaXY(p4,p3,p2,p1)
[+] 80e6	SetExitGrid(p9,p8,p7,p6,p5,p4,p3,p2,p1)
[+] 80f5	CanHear(p5,p4,p3,p2,p1)
[+] 8126	RegAnimateForever(p2,p1)
[+] 812c	Unkown812C
[+] 814e	SetBarterModifier(p1)
[+] 8152	Flee(p2,p1)

It'd be really cool, as I can't save in Access97 format...

Also if you have any idea how the "Dopcom" works, it'd probably help me a lot...