Open main menu

Difference between revisions of "SCI/Specifications/SCI virtual machine/Kernel functions"

(Merging of the SCI documentation. Work in progress)
 
(Fixed typo, "wrod" -> "word")
 
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
'''WORK IN PROGRESS. DOCUMENT INCOMPLETE'''
=Kernel functions=
=Kernel functions=


Line 16: Line 14:
<tt>02 00 80 00 0a 00</tt>
<tt>02 00 80 00 0a 00</tt>
:before calling <tt>Load()</tt>.
:before calling <tt>Load()</tt>.


Return values are returned into the accumulator, unless stated otherwise. If return type is stated as (<tt>void</tt>), then the accumulator is not modified.
Return values are returned into the accumulator, unless stated otherwise. If return type is stated as (<tt>void</tt>), then the accumulator is not modified.


==Parameter types==
==Parameter types==
SCI0 uses only little endian 16 bit integer values for parameters. However, this document distinguishes between different uses of those integers by defining the following variable types:
SCI0 uses only little endian 16 bit integer values for parameters. However, this document distinguishes between different uses of those integers by defining the following variable types:


;(word)
;(word)
 
:16 bit signed little endian integer
:16 bit signed little endian integer
;(HeapPtr)
;(HeapPtr)
Line 44: Line 41:


Most functions exit gracefully if either a NULL HeapPtr or DblList is provided.
Most functions exit gracefully if either a NULL HeapPtr or DblList is provided.


==SCI0 Kernel functions==
==SCI0 Kernel functions==
Line 52: Line 48:
word ResType, word ResNr;</syntax>
word ResType, word ResNr;</syntax>


(word) <tt>ResType:</tt> The resource type number |@ 0x80 (as in the patch files)
(word) <tt>ResType:</tt> The resource type number <nowiki>| 0x80</nowiki> (as in the patch files)<br>
(word) <tt>ResNr:</tt> The resource number
(word) <tt>ResNr:</tt> The resource number<br>


Returns: (&FarPtr): A HeapPtr pointing to an actual pointer on the heap.
Returns: (&FarPtr): A HeapPtr pointing to an actual pointer on the heap.<br>


Loads a resource. The returned <tt>HeapPtr</tt> points to a special point on the heap where a pointer (32 bits) to the memory location of the specified resource is located. If the resource type equals sci_memory, the resource number is interpreted as a memory size instead; the specified number of bytes is allocated dynamically, and a handle returned.
Loads a resource. The returned <tt>HeapPtr</tt> points to a special point on the heap where a pointer (32 bits) to the memory location of the specified resource is located. If the resource type equals sci_memory, the resource number is interpreted as a memory size instead; the specified number of bytes is allocated dynamically, and a handle returned.


===Kernel function <tt>0x01: UnLoad(word, word)</tt>===
===Kernel function <tt>0x01: UnLoad(word, word)</tt>===
Line 64: Line 59:
word ResType, word ResNr;</syntax>
word ResType, word ResNr;</syntax>


(word) <tt>ResType:</tt> The resource type number |@ 0x80
(word) <tt>ResType:</tt> The resource type number | 0x80<br>
(word) <tt>ResNr:</tt> The resource number
(word) <tt>ResNr:</tt> The resource number<br>


Returns: (void)
Returns: (void)
Line 75: Line 70:
word ScriptNr, word DispatchNr;</syntax>
word ScriptNr, word DispatchNr;</syntax>


(word) <tt>ScriptNr:</tt> Number of the script to reference
(word) <tt>ScriptNr:</tt> Number of the script to reference<br>
(word) <tt>DispatchNr:</tt> Number of the Dispatch entry inside the script to reference
(word) <tt>DispatchNr:</tt> Number of the Dispatch entry inside the script to reference<br>


Returns: (HeapPtr): The address pointed to by the specified element of the dispatch/exports table (script block type #7).
Returns: (HeapPtr): The address pointed to by the specified element of the dispatch/exports table (script block type #7).
Line 86: Line 81:
word ScriptNumber;</syntax>
word ScriptNumber;</syntax>


(word) <tt>ScriptNumber</tt>
(word) <tt>ScriptNumber</tt><br>


Returns: (void)
Returns: (void)<br>


Disposes a script. Unloads it, removes its entries from the class table, and frees the associated heap memory.
Disposes a script. Unloads it, removes its entries from the class table, and frees the associated heap memory.
Line 96: Line 91:
HeapPtr object;</syntax>
HeapPtr object;</syntax>


(HeapPtr) <tt>object:</tt> The object to clone
(HeapPtr) <tt>object:</tt> The object to clone<br>


Returns: (HeapPtr) The address of the clone
Returns: (HeapPtr) The address of the clone<br>


This function clones a Class or Object by copying it as a whole and mofifying the -info- selector so that it contains 1. Objects with -info- set to 0x8000 (Classes) are stripped of their selector name area, and both Objects and Classes are stripped of the function selector area.
This function clones a Class or Object by copying it as a whole and mofifying the -info- selector so that it contains 1. Objects with -info- set to 0x8000 (Classes) are stripped of their selector name area, and both Objects and Classes are stripped of the function selector area.
Line 106: Line 101:
HeapPtr clone;</syntax>
HeapPtr clone;</syntax>


(HeapPtr) <tt>clone:</tt> The clone to dispose
(HeapPtr) <tt>clone:</tt> The clone to dispose<br>


Returns: (void)
Returns: (void)<br>


Frees all memory associated with a cloned object (as produced by Clone()).
Frees all memory associated with a cloned object (as produced by Clone()).
Line 127: Line 122:
word PicNr[, word Animation, word Flags, word DefaultPalette];
word PicNr[, word Animation, word Flags, word DefaultPalette];


(word) PicNr: The resource number of the picture to draw
(word) PicNr: The resource number of the picture to draw<br>
(word) Animation: One of the following animation modes:
(word) Animation: One of the following animation modes:


Line 152: Line 147:
</ol>
</ol>


The animation is executed when kAnimate() (see KAnimateSection [*]) is invoked. If not specified, it is assumed to be the same animation as last time.
The animation is executed when kAnimate() (see (see [[SCI/Specifications/SCI_in_action/Views_and_animation_in_SCI|Views and animation in SCI]] section) is invoked. If not specified, it is assumed to be the same animation as last time.
(word) Flags:
(word) Flags:


Bit 0: Clear screen before drawing
* Bit 0: Clear screen before drawing
Bit 1-f: unknown, probably unused
* Bit 1-f: unknown, probably unused


If not specified, it defaults to 1.
If not specified, it defaults to 1.
Line 162: Line 157:
Some interpreter versions older than 0.000.502 interpret this parameter inversely, and have 0 as a default.
Some interpreter versions older than 0.000.502 interpret this parameter inversely, and have 0 as a default.


(word) DefaultPalette: The default palette number to use for drawing
(word) DefaultPalette: The default palette number to use for drawing<br>


Returns: (void)
Returns: (void)<br>


The second parameter does not appear to affect anything. In QfG1, it appears to be set to <tt>0x64</tt> constantly. <tt>DefaultPalette</tt> is used to differentiate between day and night in QfG1. Palette 1 is used for "night" pictures, Palette 0 for "day" pictures there. The picture is drawn to the background image (which is used for restauration of everything with the exception of the mouse pointer). To bring it to the foreground, <tt>Animate()</tt> must be used.
The second parameter does not appear to affect anything. In QfG1, it appears to be set to <tt>0x64</tt> constantly. <tt>DefaultPalette</tt> is used to differentiate between day and night in QfG1. Palette 1 is used for "night" pictures, Palette 0 for "day" pictures there. The picture is drawn to the background image (which is used for restauration of everything with the exception of the mouse pointer). To bring it to the foreground, <tt>Animate()</tt> must be used.
Line 178: Line 173:
[(word) NewPicNotValid];</syntax>
[(word) NewPicNotValid];</syntax>


[(word) <tt>NewPicNotValid</tt>]: The new value of the "PicNotValid" flag.
[(word) <tt>NewPicNotValid</tt>]: The new value of the "PicNotValid" flag.<br>


Returns: (word): The previous value of the "PicNotValid" flag
Returns: (word): The previous value of the "PicNotValid" flag<br>


This sets the <tt>PicNotValid</tt> flag that determines whether or not the current background picture should be considered "valid" by the other kernel functions.
This sets the <tt>PicNotValid</tt> flag that determines whether or not the current background picture should be considered "valid" by the other kernel functions.
Line 188: Line 183:
[DblList ViewList], [word cycle];</syntax>
[DblList ViewList], [word cycle];</syntax>


[(DblList) <tt>ViewList</tt>]: List of views that are to be drawn on top of the background picture
[(DblList) <tt>ViewList</tt>]: List of views that are to be drawn on top of the background picture<br>
(word) <unknown>
(word) <unknown><br>


Returns: (void)  
Returns: (void)<br>


This function draws a background picture plus some views to the foreground. If the background picture had not been drawn previously, it is animated with the animation style set during kDrawPic (see section Kernel function 0x08). Drawing the views is a rather complex issue. Refer to Views and animation in SCI section for its description.
This function draws a background picture plus some views to the foreground. If the background picture had not been drawn previously, it is animated with the animation style set during kDrawPic (see section [[SCI/Specifications/SCI_virtual_machine/Kernel_functions#Kernel_function_0x08:_DrawPic.28word.5B.2C_word.2C_word.2C_word.5D.29|Kernel function 0x08]]). Drawing the views is a rather complex issue. Refer to [[SCI/Specifications/SCI in action/Views and animation in SCI|Views and animation in SCI]] section for its description.


===Kernel function 0x0c: <tt>SetNowSeen(DblList)</tt>===
===Kernel function 0x0c: <tt>SetNowSeen(DblList)</tt>===
Line 199: Line 194:
DblList ViewList;</syntax>
DblList ViewList;</syntax>


(DblList) <tt>ViewList</tt>: List of affected views
(DblList) <tt>ViewList</tt>: List of affected views<br>


Returns: (void)
Returns: (void)<br>


===Kernel function <tt>0x0d: NumLoops(HeapPtr)</tt>===
===Kernel function <tt>0x0d: NumLoops(HeapPtr)</tt>===
Line 207: Line 202:
HeapPtr object;</syntax>
HeapPtr object;</syntax>


(HeapPtr) <tt>object:</tt> The object which the view selector should be taken from
(HeapPtr) <tt>object:</tt> The object which the view selector should be taken from<br>


Returns: (word) The number of loops in the view
Returns: (word) The number of loops in the view<br>


This function looks up the view selector in the specified object, loads the view resource associated with it, and checks for the number of animation loops in the view.
This function looks up the view selector in the specified object, loads the view resource associated with it, and checks for the number of animation loops in the view.
Line 217: Line 212:
HeapPtr object;</syntax>
HeapPtr object;</syntax>


HeapPtr <tt>object:</tt> The object which the selectors should be taken from
HeapPtr <tt>object:</tt> The object which the selectors should be taken from<br>


Returns: (word) The number of cels in the loop
Returns: (word) The number of cels in the loop<br>


This function looks up one specific loop in a specific view (both are taken from selectors with the same name from the object pointed to by the parameter) and returns the number of cels (animation frames) in it.
This function looks up one specific loop in a specific view (both are taken from selectors with the same name from the object pointed to by the parameter) and returns the number of cels (animation frames) in it.
Line 227: Line 222:
word view, word loop, word cel;</syntax>
word view, word loop, word cel;</syntax>


(HeapPtr) <tt>view:</tt> The view we're searching in <tt>loop:</tt> The loop the cel is contained in <tt>cel:</tt> The cel we're interested in
(HeapPtr) <tt>view:</tt> The view we're searching in <tt>loop:</tt> The loop the cel is contained in <tt>cel:</tt> The cel we're interested in<br>
 
Returns: (word) The width of the cel identified by the tuple (view, loop, cel).


===Kernel function 0x0f: CelWide(word view, word loop, word cel)===
Returns: (word) The width of the cel identified by the tuple (view, loop, cel).<br>
<syntax type="C">kfunct 0x10: CelHigh();
word view, word loop, word cel;</syntax>


(HeapPtr) <tt>view:</tt> The view we're searching in <tt>loop:</tt> The loop the cel is contained in <tt>cel:</tt> The cel we're interested in


Returns: (word) The height of the cel identified by the tuple (view, loop, cel).


===Kernel function <tt>0x11: DrawCel(word, word, word, Point, word)</tt>===
===Kernel function <tt>0x11: DrawCel(word, word, word, Point, word)</tt>===
Line 243: Line 232:
word view, word loop, word cel, Point pos, word priority;</syntax>
word view, word loop, word cel, Point pos, word priority;</syntax>


(word) <tt>view:</tt> Number of the view resource to display
(word) <tt>view:</tt> Number of the view resource to display<br>
(word) <tt>loop:</tt> Number of the loop in the view resource to display
(word) <tt>loop:</tt> Number of the loop in the view resource to display<br>
(word) <tt>cel:</tt> Number of the cel inside the loop to display
(word) <tt>cel:</tt> Number of the cel inside the loop to display<br>
(Point) <tt>pos:</tt> Position the cel should be drawn to
(Point) <tt>pos:</tt> Position the cel should be drawn to<br>
(word) <tt>priority:</tt> Priority to draw the cel with
(word) <tt>priority:</tt> Priority to draw the cel with<br>


Returns: (void)
Returns: (void)<br>


Explicitly draws a cel, specified by the complete tuple (view, loop, cel), to a specified position. Invalid loop/cel values are assumed to be 0.
Explicitly draws a cel, specified by the complete tuple (view, loop, cel), to a specified position. Invalid loop/cel values are assumed to be 0.
Line 257: Line 246:
DblList picviews;</syntax>
DblList picviews;</syntax>


(DblList) <tt>picviews:</tt> A doubly linked list of PicViews, i.e. objects that are drawn statically onto the background picture
(DblList) <tt>picviews:</tt> A doubly linked list of PicViews, i.e. objects that are drawn statically onto the background picture<br>


Returns: (void)
Returns: (void)<br>


This function stores the list of PicViews for later use by the Animate() syscall. See Kernel function 0x0b section for more details.
This function stores the list of PicViews for later use by the Animate() syscall. See [[SCI/Specifications/SCI_virtual_machine/Kernel_functions#Kernel_function_0x0b:_Animate.28.5BDblList.5D.2C_.5Bword.5D.29|Kernel function 0x0b]] section for more details.


===Kernel function 0x13: NewWindow(Rect, HeapPtr, word, word, word, word)===
===Kernel function 0x13: NewWindow(Rect, HeapPtr, word, word, word, word)===
Line 267: Line 256:
Rect Boundaries, HeapPtr Title, word Flags, word Priority, word FGColor, word BGColor;</syntax>
Rect Boundaries, HeapPtr Title, word Flags, word Priority, word FGColor, word BGColor;</syntax>


(Rect) <tt>Boundaries:<tt> The bounding rectangle of the window
(Rect) <tt>Boundaries:<tt> The bounding rectangle of the window<br>
(HeapPtr) <tt>Title:</tt> A pointer to the window title
(HeapPtr) <tt>Title:</tt> A pointer to the window title<br>
(word) <tt>Flags:</tt>
(word) <tt>Flags:</tt><br>


* bit 0 - transparency
* bit 0 - transparency
Line 277: Line 266:
* bit 7 - don't draw anything
* bit 7 - don't draw anything


(word) <tt>Priority:</tt> The priority at which the window should be drawn, or -1 to force on-top drawing
(word) <tt>Priority:</tt> The priority at which the window should be drawn, or -1 to force on-top drawing<br>
(word) <tt>FGColor:</tt> The foreground color for the window
(word) <tt>FGColor:</tt> The foreground color for the window<br>
(word) <tt>BGColor:</tt> The background color
(word) <tt>BGColor:</tt> The background color<br>


Returns: (HeapPtr): The position of the window structure on the heap
Returns: (HeapPtr): The position of the window structure on the heap<br>


This function creates a window (see also Windows, Dialogs and Controls section), sets this window as the active port, draws the window (if neccessary), and returns with the window's heap address.
This function creates a window (see also [[SCI/Specifications/Graphics/Windows, Dialogs and Controls|Windows, Dialogs and Controls]] section), sets this window as the active port, draws the window (if neccessary), and returns with the window's heap address.


===Kernel function 0x14: GetPort()===
===Kernel function 0x14: GetPort()===
Line 295: Line 284:
HeapPtr NewPort;</syntax>
HeapPtr NewPort;</syntax>


(HeapPtr) <tt>NewPort:</tt> The new port to set
(HeapPtr) <tt>NewPort:</tt> The new port to set<br>


Returns: (void)
Returns: (void)<br>


This selects the new port which many kernel functions will draw to.
This selects the new port which many kernel functions will draw to.
Line 307: Line 296:
HeapPtr Window;</syntax>
HeapPtr Window;</syntax>


(HeapPtr) <tt>Window:</tt> The heap address of the window to destroy
(HeapPtr) <tt>Window:</tt> The heap address of the window to destroy<br>


Returns: (void)
Returns: (void)<br>


Destroys a window and frees the associated heap structure.
Destroys a window and frees the associated heap structure.
Line 317: Line 306:
HeapPtr Control;</syntax>
HeapPtr Control;</syntax>


(HeapPtr) <tt>Control:</tt> The heap address of the Control to draw
(HeapPtr) <tt>Control:</tt> The heap address of the Control to draw<br>


Returns: (void)
Returns: (void)<br>


This function draws a Control (see Windows, Dialogs and Controls section for details). Please note that the correct port must be selected beforehand.
This function draws a Control (see [[SCI/Specifications/Graphics/Windows, Dialogs and Controls|Windows, Dialogs and Controls]] section for details). Please note that the correct port must be selected beforehand.


===Kernel function 0x18: HiliteControl(HeapPtr)===
===Kernel function 0x18: HiliteControl(HeapPtr)===
Line 327: Line 316:
HeapPtr Control;</syntax>
HeapPtr Control;</syntax>


(HeapPtr) <tt>Control:</tt> The control to highlight
(HeapPtr) <tt>Control:</tt> The control to highlight<br>


Returns: (void)
Returns: (void)<br>


This function is used to highlight a control by drawing it with an inverted color scheme. It requires the correct port to be set beforehand. See Windows, Dialogs and Controls section for details on the windowing Control system.
This function is used to highlight a control by drawing it with an inverted color scheme. It requires the correct port to be set beforehand. See Windows, Dialogs and Controls section for details on the windowing Control system.
Line 337: Line 326:
HeapPtr Control, HeapPtr Event;</syntax>
HeapPtr Control, HeapPtr Event;</syntax>


(HeapPtr) <tt>Control:</tt> A heap pointer to the Control to edit
(HeapPtr) <tt>Control:</tt> A heap pointer to the Control to edit<br>
(HeapPtr) <tt>Event:</tt> The event to interpret
(HeapPtr) <tt>Event:</tt> The event to interpret<br>


Returns: (void)
Returns: (void)<br>


This function will apply the event provided to edit a type 3 (Edit window) Control (see Windows, Dialogs and Controls section for a description of the control system). Normal keypresses are added to the area pointed to by Control::text, unless the total string length would be greater than Control::max. Cursor keys, backspace and a few other keys may be used to manipulate the control. In FreeSCI, some of the libreadline control keys can be used to edit and move the cursor as well. If it is called to edit a Control which is not of type 3, it returns without error. Please note that the correct port (usually the window which the Control was drawn in) must be selected beforehand.
This function will apply the event provided to edit a type 3 (Edit window) Control (see [[SCI/Specifications/Graphics/Windows, Dialogs and Controls|Windows, Dialogs and Controls]] section for a description of the control system). Normal keypresses are added to the area pointed to by Control::text, unless the total string length would be greater than Control::max. Cursor keys, backspace and a few other keys may be used to manipulate the control. In FreeSCI, some of the libreadline control keys can be used to edit and move the cursor as well. If it is called to edit a Control which is not of type 3, it returns without error. Please note that the correct port (usually the window which the Control was drawn in) must be selected beforehand.


===Kernel function 0x1a: TextSize(HeapPtr, HeapPtr, word[, word])===
===Kernel function 0x1a: TextSize(HeapPtr, HeapPtr, word[, word])===
Line 348: Line 337:
HeapPtr dest, HeapPtr src, word font[, word maxwidth];</syntax>
HeapPtr dest, HeapPtr src, word font[, word maxwidth];</syntax>


(HeapPtr) <tt>dest:</tt> The destination to write the rectangle to
(HeapPtr) <tt>dest:</tt> The destination to write the rectangle to<br>
(HeapPtr) <tt>src:</tt> A pointer to the string to analyze
(HeapPtr) <tt>src:</tt> A pointer to the string to analyze<br>
(word) <tt>font:</tt> The number of the font resource to use for this check
(word) <tt>font:</tt> The number of the font resource to use for this check<br>
(word) <tt>maxwidth:</tt> The maximum width to allow for the text (defaults to 192)
(word) <tt>maxwidth:</tt> The maximum width to allow for the text (defaults to 192)<br>


Returns: (void)
Returns: (void)<br>


This function calculates the width and height the specified text will require to be displayed with the specified font and the specified maximum width. The result will be written to the (you guessed it) specified destination on the heap. The result is a rectangle structure: The first four bytes equal to zero, the next word is the height, and the last word is the width.
This function calculates the width and height the specified text will require to be displayed with the specified font and the specified maximum width. The result will be written to the (you guessed it) specified destination on the heap. The result is a rectangle structure: The first four bytes equal to zero, the next word is the height, and the last word is the width.
Line 361: Line 350:
String text, word commands...;</syntax>
String text, word commands...;</syntax>


(String) <tt>text:</tt> The text to work with
(String) <tt>text:</tt> The text to work with<br>
(word) <tt>commands...:</tt> A sequence of commands with parameters:
(word) <tt>commands...:</tt> A sequence of commands with parameters:<br>
* 100: 2 params, (X,Y) coord of where to write on the port.
* 100: 2 params, (X,Y) coord of where to write on the port.
* 101: 1 param, -1, 0 or 1 (align right (-1), left (0) or center (1).
* 101: 1 param, -1, 0 or 1 (align right (-1), left (0) or center (1).
Line 373: Line 362:
* 108: 1 param, (handle to stored pixels) restore under. With this command, the text and all other parameters are ignored.
* 108: 1 param, (handle to stored pixels) restore under. With this command, the text and all other parameters are ignored.


Returns: (void) or (&FarPtr)(see above)
Returns: (void) or (&FarPtr)(see above)<br>


This function executes the specified commands, then draws the supplied text to the active port (unless command 108 was executed).  
This function executes the specified commands, then draws the supplied text to the active port (unless command 108 was executed).


===Kernel function 0x1c: GetEvent(word, HeapPtr)===
===Kernel function 0x1c: GetEvent(word, HeapPtr)===
Line 385: Line 374:
* bit 0 - 14: Bit mask for the events to be returned.
* bit 0 - 14: Bit mask for the events to be returned.
* bit 15: Disable joystick polling
* bit 15: Disable joystick polling
(HeapPtr) <tt>Event:</tt> An Object on the stack which the results are written to.


Returns: (word): 0 if a null event was created, 1 otherwise.
(HeapPtr) <tt>Event:</tt> An Object on the stack which the results are written to<br>
 
Returns: (word): 0 if a null event was created, 1 otherwise<br>


This function fills an Event object with data from the event queue. The results are written to the "type", "message" and "modifiers" selectors. See Event handling in SCI section for details.
This function fills an Event object with data from the event queue. The results are written to the "type", "message" and "modifiers" selectors. See Event handling in SCI section for details.
Line 395: Line 385:
HeapPtr Event;</syntax>
HeapPtr Event;</syntax>


(HeapPtr) <tt>Event:</tt> pointer to the Event object to convert
(HeapPtr) <tt>Event:</tt> pointer to the Event object to convert<br>


Returns: (void)
Returns: (void)<br>


This function converts a screen-relative event to a port-relative one, using the currently active port.
This function converts a screen-relative event to a port-relative one, using the currently active port.
Line 405: Line 395:
HeapPtr Event;</syntax>
HeapPtr Event;</syntax>


(HeapPtr) <tt>Event:</tt> pointer to the Event object to convert
(HeapPtr) <tt>Event:</tt> pointer to the Event object to convert<br>


Returns: (void)
Returns: (void)<br>


This function converts a port-relative event to a screen-relative one, using the currently active port.
This function converts a port-relative event to a screen-relative one, using the currently active port.
Line 415: Line 405:
HeapPtr Event;</syntax>
HeapPtr Event;</syntax>


(HeapPtr) <tt>Event:</tt> pointer to the Event object to convert
(HeapPtr) <tt>Event:</tt> pointer to the Event object to convert<br>


Returns: (HeapPtr): A pointer to the converted object
Returns: (HeapPtr): A pointer to the converted object<br>


This function converts a keyboard event to a movement event, if possible. Otherwise, the function returns without error. See Event handling in SCI section for details.
This function converts a keyboard event to a movement event, if possible. Otherwise, the function returns without error. See Event handling in SCI section for details.
Line 425: Line 415:
word mode;</syntax>
word mode;</syntax>


(word) <tt>mode:</tt> 1 to draw, 0 to clear
(word) <tt>mode:</tt> 1 to draw, 0 to clear<br>


Returns: (void)
Returns: (void)<br>


Either draws or clears (overdraws with black) the menu bar.
Either draws or clears (overdraws with black) the menu bar.
Line 435: Line 425:
HeapPtr event[, word flag];</syntax>
HeapPtr event[, word flag];</syntax>


(HeapPtr) <tt>event:</tt> The event to interpret
(HeapPtr) <tt>event:</tt> The event to interpret<br>
(word) flag: (unknown)
(word) flag: (unknown)<br>


Returns: (word) The menu index of a selected option, -1 if no menu option was selected, or 0 if the event passed through all of the menu system's filters.
Returns: (word) The menu index of a selected option, -1 if no menu option was selected, or 0 if the event passed through all of the menu system's filters.
Line 446: Line 436:
HeapPtr title, HeapPtr content;</syntax>
HeapPtr title, HeapPtr content;</syntax>


(HeapPtr) <tt>title:</tt> The menu title
(HeapPtr) <tt>title:</tt> The menu title<br>
(HeapPtr) <tt>content:</tt> The menu options
(HeapPtr) <tt>content:</tt> The menu options<br>


Returns: (void)
Returns: (void)<br>


This function adds a menu to the menu bar. The menu title is passed in the first parameter, the second parameter contains a heap pointer to the menu entries. They are contained in one single string; the following special characters/character combinations are used:
This function adds a menu to the menu bar. The menu title is passed in the first parameter, the second parameter contains a heap pointer to the menu entries. They are contained in one single string; the following special characters/character combinations are used:
Line 463: Line 453:
HeapPtr text;</syntax>
HeapPtr text;</syntax>


(HeapPtr) <tt>text:</tt> The text to draw
(HeapPtr) <tt>text:</tt> The text to draw<br>


Returns: (void)
Returns: (void)<br>


Draws the specified text to the title bar.
Draws the specified text to the title bar.


Kernel function 0x24: Parse(HeapPtr, HeapPtr)
===Kernel function 0x24: Parse(HeapPtr, HeapPtr)===
id2506635


kfunct 0x24: Parse();
kfunct 0x24: Parse();
HeapPtr event, HeapPtr input;
HeapPtr event, HeapPtr input;


(HeapPtr) event: The event to generate
(HeapPtr) event: The event to generate<br>
(HeapPtr) input: The input line to parse
(HeapPtr) input: The input line to parse<br>


Returns: (word) 1 on success, 0 otherwise
Returns: (word) 1 on success, 0 otherwise<br>


This function parses the input line and generates a parse event (type 0x80). See The Parser and Event handling in SCI sections for details.
This function parses the input line and generates a parse event (type 0x80). See The Parser and Event handling in SCI sections for details.
Line 487: Line 476:
HeapPtr said_block;</syntax>
HeapPtr said_block;</syntax>


(HeapPtr) <tt>said_block:</tt> Pointer to a Said block
(HeapPtr) <tt>said_block:</tt> Pointer to a Said block<br>


Returns: (word) 1 if the line last parsed meets the criteria of the supplied said_block, 0 otherwise.
Returns: (word) 1 if the line last parsed meets the criteria of the supplied said_block, 0 otherwise.
Line 497: Line 486:
HeapPtr list;</syntax>
HeapPtr list;</syntax>


(DblList) <tt>list:</tt> List of script objects to examine
(DblList) <tt>list:</tt> List of script objects to examine<br>


Returns: (void)
Returns: (void)<br>


This function sets the synonyms used by the parser. Synonyms are used to replace specified word groups with other word groups. The list contains a collection of script objects; all synonyms defined by the corresponding script (which can be identified by evaluating the 'number' selector of the script object) are added to the list of active synonyms.
This function sets the synonyms used by the parser. Synonyms are used to replace specified word groups with other word groups. The list contains a collection of script objects; all synonyms defined by the corresponding script (which can be identified by evaluating the 'number' selector of the script object) are added to the list of active synonyms.
Line 506: Line 495:
<syntax type="C">kfunct 0x27: HaveMouse();</syntax>
<syntax type="C">kfunct 0x27: HaveMouse();</syntax>


Returns: (word) 1 if a mouse is available, 0 if not.
Returns: (word) 1 if a mouse is available, 0 if not<br>


This function simply returns a flag containing the availability of a pointing device.
This function simply returns a flag containing the availability of a pointing device.
Line 514: Line 503:
word resource, word visible[, Point coordinates];</syntax>
word resource, word visible[, Point coordinates];</syntax>


(word) <tt>resource:</tt> The cursor resource to use for drawing the mouse pointer
(word) <tt>resource:</tt> The cursor resource to use for drawing the mouse pointer<br>
(word) <tt>visible:</tt> 1 if the mouse pointer should be visible, 0 if not
(word) <tt>visible:</tt> 1 if the mouse pointer should be visible, 0 if not<br>
(Point) <tt>coordinates:</tt> The coordinates (relative to the wm-port) to move the mouse pointer to
(Point) <tt>coordinates:</tt> The coordinates (relative to the wm-port) to move the mouse pointer to<br>


Returns: (void)
Returns: (void)<br>


This function can change the appearance and position of the mouse pointer. If no position is provided, the position remains unchanged.
This function can change the appearance and position of the mouse pointer. If no position is provided, the position remains unchanged.
Line 526: Line 515:
String fname, word mode;</syntax>
String fname, word mode;</syntax>


(String) <tt>fname:</tt> The file name
(String) <tt>fname:</tt> The file name<br>
(word) <tt>mode:</tt> The mode to open the file with
(word) <tt>mode:</tt> The mode to open the file with<br>


Returns: (word) a file handle on success, 12#12 on error
Returns: (word) a file handle on success, 12#12 on error<br>


Tries to open or create a file in the CWD with the specified file name. The following modes are valid:
Tries to open or create a file in the CWD with the specified file name. The following modes are valid:
Line 541: Line 530:
word filehandle, String data;</syntax>
word filehandle, String data;</syntax>


(word) <tt>filehandle:</tt> Handle of the file to write to
(word) <tt>filehandle:</tt> Handle of the file to write to<br>
(String) <tt>data:</tt> The string to write to the file
(String) <tt>data:</tt> The string to write to the file<br>


Returns: (void)
Returns: (void)<br>


Writes a zero-terminated string to a file.
Writes a zero-terminated string to a file.
Line 552: Line 541:
String dest, word maxsize, word handle;</syntax>
String dest, word maxsize, word handle;</syntax>


(String) <tt>dest:</tt> Pointer to the destination buffer
(String) <tt>dest:</tt> Pointer to the destination buffer<br>
(word) <tt>maxsize:</tt> Maximum number of bytes to read
(word) <tt>maxsize:</tt> Maximum number of bytes to read<br>
(word) <tt>handle:</tt> Handle of the file to read from
(word) <tt>handle:</tt> Handle of the file to read from<br>


Returns: (word) The number of bytes actually read.
Returns: (word) The number of bytes actually read<br>


===Kernel function 0x2c: FClose(word)===
===Kernel function 0x2c: FClose(word)===
Line 562: Line 551:
word filehandle;</syntax>
word filehandle;</syntax>


(word) <tt>filehandle:</tt> Handle of the file to close
(word) <tt>filehandle:</tt> Handle of the file to close<br>


Returns: (void)
Returns: (void)<br>


Closes a previously opened file.
Closes a previously opened file.
Line 572: Line 561:
String game_id, word save_nr, String save_description, String version;</syntax>
String game_id, word save_nr, String save_description, String version;</syntax>


(String) <tt>game_id:</tt> The game object's ID string (e.g. "SQ3")
(String) <tt>game_id:</tt> The game object's ID string (e.g. "SQ3")<br>
(word) <tt>save_nr:</tt> "slot" the game is to be saved to
(word) <tt>save_nr:</tt> "slot" the game is to be saved to<br>
(String) <tt>save_description:</tt> String description of the game
(String) <tt>save_description:</tt> String description of the game<br>
(String) <tt>version:</tt> Stringified game version number
(String) <tt>version:</tt> Stringified game version number<br>


Returns: (word) 1 on success, 0 if an error occured while saving
Returns: (word) 1 on success, 0 if an error occured while saving<br>


This function saves the game state (heap, windows, call stack, view list, sound state etc.) to the savegame with the numeric id save_nr and the description save_description. game_id and version are stored alongside, for verification when the game state is restored.
This function saves the game state (heap, windows, call stack, view list, sound state etc.) to the savegame with the numeric id save_nr and the description save_description. game_id and version are stored alongside, for verification when the game state is restored.
Line 585: Line 574:
String game_id, word save_nr, String version;</syntax>
String game_id, word save_nr, String version;</syntax>


(String) <tt>game_id:</tt> The game object's ID string
(String) <tt>game_id:</tt> The game object's ID string<br>
(word) <tt>save_nr:</tt> Number of the save game to restore
(word) <tt>save_nr:</tt> Number of the save game to restore<br>
(String) <tt>version:</tt> The game object's version number
(String) <tt>version:</tt> The game object's version number<br>


Returns: (void)
Returns: (void)<br>


This function restores a previously saved game. It should only return if restoring failed.
This function restores a previously saved game. It should only return if restoring failed.
Line 595: Line 584:
===Kernel function 0x2f: RestartGame()===
===Kernel function 0x2f: RestartGame()===
<syntax type="C">kfunct 0x2f: RestartGame();</syntax>
<syntax type="C">kfunct 0x2f: RestartGame();</syntax>
Returns: never
Returns: never<br>


If this function is invoked, the following things happen:
If this function is invoked, the following things happen:
Line 605: Line 594:
* The heap status is reset, but the heap is not cleared
* The heap status is reset, but the heap is not cleared


After this is done, the engine restarts at a certain point (see Interpreter initialization and the main execution loop section for more details), re-initializes the stack, and executes the replay method of the game object.
After this is done, the engine restarts at a certain point (see [[SCI/Specifications/SCI virtual machine/Interpreter initialization and the main execution loop|Interpreter initialization and the main execution loop]] section for more details), re-initializes the stack, and executes the replay method of the game object.


===Kernel function 0x30: GameIsRestarting()===
===Kernel function 0x30: GameIsRestarting()===
<syntax type="C">kfunct 0x30: GameIsRestarting();</syntax>
<syntax type="C">kfunct 0x30: GameIsRestarting();</syntax>


Returns: (word) 1 if the game is restarting, 0 if not
Returns: (word) 1 if the game is restarting, 0 if not<br>


===Kernel function 0x31: DoSound(word, ...])===
===Kernel function 0x31: DoSound(word, ...])===
Line 616: Line 605:
word action, ...;</syntax>
word action, ...;</syntax>


(word) <tt>action:</tt> The sound command subfunction number
(word) <tt>action:</tt> The sound command subfunction number<br>


Returns: (see below)
Returns: (see below)<br>


'action' may be one of the following:
'action' may be one of the following:
Line 642: Line 631:
word 0, Object sound_obj;</syntax>
word 0, Object sound_obj;</syntax>


(word) <tt>0:</tt> subfunction identifier
(word) <tt>0:</tt> subfunction identifier<br>
(Object) <tt>sound_obj:</tt> The sound object affected
(Object) <tt>sound_obj:</tt> The sound object affected<br>


Returns: (void)
Returns: (void)<br>


Initializes the specified sound object. This will set the 'status' selector of the object to 1 ('initialized'), and load the sound indicated by the 'number' selector into the sound driver.
Initializes the specified sound object. This will set the 'status' selector of the object to 1 ('initialized'), and load the sound indicated by the 'number' selector into the sound driver.
Line 653: Line 642:
word 1, Object sound_obj;</syntax>
word 1, Object sound_obj;</syntax>


(word) <tt>1:</tt> The subfunction identifier
(word) <tt>1:</tt> The subfunction identifier<br>
(Object) <tt>sound_obj:</tt> The sound object affected
(Object) <tt>sound_obj:</tt> The sound object affected<br>


Returns: (void)
Returns: (void)<br>


Starts to play the song represented by the specified sound object. This will also set the 'status' selector of the object to 2 ('playing').
Starts to play the song represented by the specified sound object. This will also set the 'status' selector of the object to 2 ('playing').
Line 664: Line 653:
word 2;</syntax>
word 2;</syntax>


(word) <tt>2:</tt> The sound command subfunction number
(word) <tt>2:</tt> The sound command subfunction number<br>


Returns: (void)
Returns: (void)<br>


No action appears to be associated with this subfunction call.
No action appears to be associated with this subfunction call.
Line 674: Line 663:
word 3, Object sound_obj;</syntax>
word 3, Object sound_obj;</syntax>


(word) <tt>3</tt>: The sound command subfunction number
(word) <tt>3</tt>: The sound command subfunction number<br>
(Object) <tt>sound_obj:</tt> The sound object affected
(Object) <tt>sound_obj:</tt> The sound object affected<br>


Returns: (void)
Returns: (void)<br>


Removes the song indexed by a sound object from the sound server song list.
Removes the song indexed by a sound object from the sound server song list.
Line 685: Line 674:
word 4, word state;</syntax>
word 4, word state;</syntax>


(word) <tt>4:</tt> The sound command subfunction number
(word) <tt>4:</tt> The sound command subfunction number<br>
(word) <tt>state:</tt> 1 if sound should be active, 0 if it should be turned off
(word) <tt>state:</tt> 1 if sound should be active, 0 if it should be turned off<br>


Returns: (word) 1 if currently active, 0 if currently muted.
Returns: (word) 1 if currently active, 0 if currently muted.<br>


This function completely mutes or un-mutes the sound subsystem. If called with no parameters, it returns the current status.
This function completely mutes or un-mutes the sound subsystem. If called with no parameters, it returns the current status.
Line 696: Line 685:
word 5, Object sound_obj;</syntax>
word 5, Object sound_obj;</syntax>


(word) <tt>5:</tt> The sound command subfunction number
(word) <tt>5:</tt> The sound command subfunction number<br>
(Object) <tt>sound_obj:</tt> The sound object affected
(Object) <tt>sound_obj:</tt> The sound object affected<br>


Returns: (void)
Returns: (void)<br>


Stops playing the song represented by the specified sound object. This will set the object's 'state' selector to 0 ('stopped').
Stops playing the song represented by the specified sound object. This will set the object's 'state' selector to 0 ('stopped').
Line 707: Line 696:
word 6, Object sound_obj;</syntax>
word 6, Object sound_obj;</syntax>


(word) <tt>6:</tt> The sound command subfunction number
(word) <tt>6:</tt> The sound command subfunction number<br>
(Object) <tt>sound_obj:</tt> The sound object affected
(Object) <tt>sound_obj:</tt> The sound object affected<br>


Returns: (void)
Returns: (void)<br>


Suspends the song associated with the specified sound object. Its state is buffered, so that it can be resumed later on. The sound object's 'state' selector is set to 3 ('suspended').
Suspends the song associated with the specified sound object. Its state is buffered, so that it can be resumed later on. The sound object's 'state' selector is set to 3 ('suspended').
Line 718: Line 707:
word 7, Object sound_obj;</syntax>
word 7, Object sound_obj;</syntax>


(word) <tt>7:</tt> The sound command subfunction number
(word) <tt>7:</tt> The sound command subfunction number<br>
(Object) </tt>sound_obj:</tt> The sound object affected
(Object) </tt>sound_obj:</tt> The sound object affected<br>


Returns: (void)
Returns: (void)<br>


Resumes a previously suspended song. The 'state' selector is set to 2 ('playing').
Resumes a previously suspended song. The 'state' selector is set to 2 ('playing').
Line 729: Line 718:
word 8[, word volume];</syntax>
word 8[, word volume];</syntax>


(word) <tt>8:</tt> The sound command subfunction number
(word) <tt>8:</tt> The sound command subfunction number<br>
(word) <tt>volume:</tt> An optional volume parameter
(word) <tt>volume:</tt> An optional volume parameter<br>


Returns: (word) The currently set sound volume (0 to 0xf)
Returns: (word) The currently set sound volume (0 to 0xf)<br>


This subfunction retrieves and returns the current sound volume. If a second parameter is supplied the volume will be set to the value of this parameter.
This subfunction retrieves and returns the current sound volume. If a second parameter is supplied the volume will be set to the value of this parameter.
Line 740: Line 729:
word 9, Object sound_obj;</syntax>
word 9, Object sound_obj;</syntax>


(word) <tt>9:</tt> The sound command subfunction number
(word) <tt>9:</tt> The sound command subfunction number<br>
(Object) <tt>sound_obj:</tt> The sound object affected
(Object) <tt>sound_obj:</tt> The sound object affected<br>


Returns: (void)
Returns: (void)<br>


Notifies the sound server that a sound object was modified. The song priority and number of loops (stored in the 'priority' and 'loop' selectors, respectively) are re-evaulated by the sound system.
Notifies the sound server that a sound object was modified. The song priority and number of loops (stored in the 'priority' and 'loop' selectors, respectively) are re-evaulated by the sound system.
Line 751: Line 740:
word 0xa, Object sound_obj;</syntax>
word 0xa, Object sound_obj;</syntax>


(word) <tt>0xa:</tt> The sound command subfunction number
(word) <tt>0xa:</tt> The sound command subfunction number<br>
(Object) <tt>sound_obj:</tt> The sound object affected
(Object) <tt>sound_obj:</tt> The sound object affected<br>


Returns: (void)
Returns: (void)<br>


Fades the specified song. Fading takes approximately two seconds. The song status is set to 'stopped' (0) afterwards.
Fades the specified song. Fading takes approximately two seconds. The song status is set to 'stopped' (0) afterwards.
Line 762: Line 751:
word 0xb;</syntax>
word 0xb;</syntax>


(word) <tt>0xb:</tt> The sound command subfunction number
(word) <tt>0xb:</tt> The sound command subfunction number<br>


Returns: (word) 1 if the sound driver was installed successfully, 0 if not
Returns: (word) 1 if the sound driver was installed successfully, 0 if not<br>


===Kernel function 0x31: DoSound(ALL_STOP)===
===Kernel function 0x31: DoSound(ALL_STOP)===
Line 770: Line 759:
word 0xc;</syntax>
word 0xc;</syntax>


(word) <tt>0xc:</tt> The sound command subfunction number
(word) <tt>0xc:</tt> The sound command subfunction number<br>


Returns: (void)
Returns: (void)<br>


Stops all music and sound effects.
Stops all music and sound effects.<br>


==Kernel function 0x32: NewList()===
===Kernel function 0x32: NewList()===
<syntax type="C">kfunct 0x32: NewList();</syntax>
<syntax type="C">kfunct 0x32: NewList();</syntax>


Returns: (DblList) The address of a new node list on the heap
Returns: (DblList) The address of a new node list on the heap<br>


This function allocates and initializes a node list containing no elements.
This function allocates and initializes a node list containing no elements.
Line 787: Line 776:
NodeList list;</syntax>
NodeList list;</syntax>


(NodeList) <tt>list:</tt> The list to dispose
(NodeList) <tt>list:</tt> The list to dispose<br>


Returns: (void)
Returns: (void)<br>


Frees all memory associated to a list.
Frees all memory associated to a list.
Line 797: Line 786:
word value, word key;</syntax>
word value, word key;</syntax>


(word) <tt>value:</tt> The node value
(word) <tt>value:</tt> The node value<br>
(word) <tt>key:</tt> The node key (used for searching the list)
(word) <tt>key:</tt> The node key (used for searching the list)<br>


Returns: (Node) A new node
Returns: (Node) A new node<br>


This function allocates a new node and initializes it with the key and value passed as parameters.
This function allocates a new node and initializes it with the key and value passed as parameters.
Line 808: Line 797:
DblList list;</syntax>
DblList list;</syntax>


(DblList) <tt>list:</tt> The list to examine
(DblList) <tt>list:</tt> The list to examine<br>


Returns: (Node) The first node of the list, or 0 if the list is empty
Returns: (Node) The first node of the list, or 0 if the list is empty<br>


===Kernel function 0x36: LastNode(DblList)===
===Kernel function 0x36: LastNode(DblList)===
Line 816: Line 805:
DblList list;</syntax>
DblList list;</syntax>


(DblList) <tt>list:</tt> The list to examine
(DblList) <tt>list:</tt> The list to examine<br>


Returns: (Node) The last node of the list, or 0 if the list is empty
Returns: (Node) The last node of the list, or 0 if the list is empty<br>


===Kernel function 0x37: EmptyList(DblList)===
===Kernel function 0x37: EmptyList(DblList)===
Line 824: Line 813:
DblList list;</syntax>
DblList list;</syntax>


(DblList) <tt>list:</tt> The list to check
(DblList) <tt>list:</tt> The list to check<br>


Returns: (int) 1 if list is an empty list, 0 if it isn't.
Returns: (int) 1 if list is an empty list, 0 if it isn'tv


===Kernel function 0x38: NextNode(Node)===
===Kernel function 0x38: NextNode(Node)===
Line 832: Line 821:
Node node;</syntax>
Node node;</syntax>


(Node) <tt>node:</tt> The node whose succcessor is to be found
(Node) <tt>node:</tt> The node whose succcessor is to be found<br>


Returns: (Node) The node following the supplied node, or 0 if none is available.
Returns: (Node) The node following the supplied node, or 0 if none is available.<br>


===Kernel function 0x39: PrevNode(Node)===
===Kernel function 0x39: PrevNode(Node)===
Line 840: Line 829:
Node node;</syntax>
Node node;</syntax>


(Node) <tt>node:</tt> The node whose predecessor is to be determined
(Node) <tt>node:</tt> The node whose predecessor is to be determined<br>


Returns: (Node) The supplied node's predecessor, or 0 if the node has no predecessor
Returns: (Node) The supplied node's predecessor, or 0 if the node has no predecessor<br>


===Kernel function 0x3a: NodeValue(Node)===
===Kernel function 0x3a: NodeValue(Node)===
Line 848: Line 837:
Node node;</syntax>
Node node;</syntax>


(Node) <tt>node:</tt> The node whose value is to be determined
(Node) <tt>node:</tt> The node whose value is to be determined<br>


Returns: (word) The value associated with the specified node
Returns: (word) The value associated with the specified node<br>


===Kernel function 0x3b: AddAfter(DblList, Node, Node)===
===Kernel function 0x3b: AddAfter(DblList, Node, Node)===
Line 856: Line 845:
DblList list, Node ref_node, Node new_node;</syntax>
DblList list, Node ref_node, Node new_node;</syntax>


(DblList) <tt>list:</tt> The list to insert into
(DblList) <tt>list:</tt> The list to insert into<br>
(Node) ref_node: The node in list to insert after
(Node) ref_node: The node in list to insert after<br>
(Node) new_node: The node to insert
(Node) new_node: The node to insert<br>


Returns: (void)
Returns: (void)<br>


This function inserts <tt>new_node</tt> into <tt>list</tt> as the immediate successor of <tt>ref_node</tt>.
This function inserts <tt>new_node</tt> into <tt>list</tt> as the immediate successor of <tt>ref_node</tt>.
Line 868: Line 857:
DblList list, Node node;</syntax>
DblList list, Node node;</syntax>


(DblList) <tt>list:</tt> The list the node is to be added to
(DblList) <tt>list:</tt> The list the node is to be added to<br>
(Node) node: The node to add
(Node) node: The node to add<br>


Returns: (void)
Returns: (void)<br>


This function adds a node to the beginning of a doubly linked list.
This function adds a node to the beginning of a doubly linked list.
Line 880: Line 869:
DblList list, Node node;</syntax>
DblList list, Node node;</syntax>


(DblList) <tt>list:</tt> The list to add the node to
(DblList) <tt>list:</tt> The list to add the node to<br>
(Node) <tt>node:</tt> The node to add to the list
(Node) <tt>node:</tt> The node to add to the list<br>


Returns: (void)
Returns: (void)<br>


This function adds the specified node to the end of the specified list.
This function adds the specified node to the end of the specified list.
Line 891: Line 880:
DblList list, word key;</syntax>
DblList list, word key;</syntax>


(DblList) <tt>list:</tt> The list in which the key is to be sought
(DblList) <tt>list:</tt> The list in which the key is to be sought<br>
(word) <tt>key:</tt> The key to seek
(word) <tt>key:</tt> The key to seek<br>


Returns: (Node) The node containing the key, or 0 if no node contains it
Returns: (Node) The node containing the key, or 0 if no node contains it<br>


This function searches for a specific key in the nodes of a doubly linked list.
This function searches for a specific key in the nodes of a doubly linked list.
Line 902: Line 891:
DblList list, word key;</syntax>
DblList list, word key;</syntax>


(DblList) <tt>list:</tt> The list to examine
(DblList) <tt>list:</tt> The list to examine<br>
(word) <tt>key:</tt> The key to find
(word) <tt>key:</tt> The key to find<br>


Returns: (void)
Returns: (void)<br>


This function searches in the supplied list for the specified key and removes the node containing it, if any can be found.
This function searches in the supplied list for the specified key and removes the node containing it, if any can be found.


===Kernel function 0x40: Random(word, word)===
===Kernel function 0x40: Random(word, word)===
<syntax type="C">kfunct 0x40: Random();
<syntax type="C">kfunct 0x40: Random();
word min, word max;</syntax>
word min, word max;</syntax>


(word) <tt>min:</tt> The minimum result
(word) <tt>min:</tt> The minimum result<br>
(word) <tt>max:</tt> The maximum result
(word) <tt>max:</tt> The maximum result<br>


Returns: (word) A random number between min and max (inclusive)
Returns: (word) A random number between min and max (inclusive)<br>


Kernel function 0x41: Abs(word)
===Kernel function 0x41: Abs(word)===
id2508782
<syntax type="C">kfunct 0x41: Abs();
word value;</syntax>


===kfunct 0x41: Abs();===
(word) <tt>value</tt>: The value to absolutize<br>
<syntax type="C">word value;</syntax>


(word) <tt>value:</tt> The value to absolutize
Returns: (word) The absolute value of the specified parameter<br>


Returns: (word) The absolute value of the specified parameter
This function interprets the supplied value as a signed value and returns its absolute value.  
 
This function interprets the supplied value as a signed value and returns its absolute value.


===Kernel function 0x42: Sqrt(word)===
===Kernel function 0x42: Sqrt(word)===
<syntax type="C">kfunct 0x42: Sqrt();
<syntax type="C">kfunct 0x42: Sqrt();
word value;</syntax>
word value;</syntax>


(word) <tt>value:</tt> The value to draw the square root out of
(word) <tt>value:</tt> The value to draw the square root out of<br>


Returns: (word) The square root of the supplied value
Returns: (word) The square root of the supplied value<br>


===Kernel function 0x43: GetAngle(Point, Point)===
===Kernel function 0x43: GetAngle(Point, Point)===
Line 944: Line 929:
Point origin, Point destination;</syntax>
Point origin, Point destination;</syntax>


(Point) <tt>origin:</tt> The point to look from
(Point) <tt>origin:</tt> The point to look from<br>
(Point) <tt>destination:</tt> The point to look to
(Point) <tt>destination:</tt> The point to look to<br>


Returns: (word) A positive angle between the two points, relative to the screen coordinate axis.
Returns: (word) A positive angle between the two points, relative to the screen coordinate axis.
Line 955: Line 940:
Point foo, Point bar;</syntax>
Point foo, Point bar;</syntax>


(Point) <tt>foo:</tt> A point in two-dimensional integer space
(Point) <tt>foo:</tt> A point in two-dimensional integer space<br>
(Point) <tt>bar:</tt> Another two-dimensional integer point
(Point) <tt>bar:</tt> Another two-dimensional integer point<br>


Returns: (int) The euklidian distance between the points foo and bar
Returns: (int) The euklidian distance between the points foo and bar<br>


===Kernel function 0x45: Wait(word)===
===Kernel function 0x45: Wait(word)===
Line 965: Line 950:
word ticks;</syntax>
word ticks;</syntax>


(word) <tt>ticks:</tt> The number of game ticks (60 Hz beats) to wait
(word) <tt>ticks:</tt> The number of game ticks (60 Hz beats) to wait<br>


Returns: (word) The time passed in between the finish of the last Wait() syscall
Returns: (word) The time passed in between the finish of the last Wait() syscall<br>


Kernel function 0x46: GetTime([word])
===Kernel function 0x46: GetTime([word])===
id2509029
<syntax type="C">kfunct 0x46: GetTime();
word mode;</syntax>


===kfunct 0x46: GetTime();===
(word) <tt>mode:</tt> If this parameter is supplied, the time of day is returned.
<syntax type="C">word mode;</syntax>


(wrod) <tt>mode:</tt> If this parameter is supplied, the time of day is returned.
Returns: (word) Either the time of day in seconds, or the elapsed number of ticks since the interpreter started.<br>


Returns: (word) Either the time of day in seconds, or the elapsed number of ticks since the interpreter started.
This function is somewhat strange, because it determines its behavior not by the value of a parameter passed, but by its presence instead. Please note that the time of day in this case does not distinguish between am and pm.
 
This function is somewhat strange, because it determines its behaviour not by the value of a parameter passed, but by its presence instead. Please note that the time of day in this case does not distinguish between am and pm.


===Kernel function 0x47: StrEnd(HeapPtr)===
===Kernel function 0x47: StrEnd(HeapPtr)===
Line 985: Line 968:
HeapPtr string;</syntax>
HeapPtr string;</syntax>


(HeapPtr) <tt>string:</tt> The string whose terminator should be found
(HeapPtr) <tt>string:</tt> The string whose terminator should be found<br>


Returns: (HeapPtr) The address of the null terminator of the indexed string
Returns: (HeapPtr) The address of the null terminator of the indexed string<br>


===Kernel function 0x48: StrCat(HeapPtr, HeapPtr)===
===Kernel function 0x48: StrCat(HeapPtr, HeapPtr)===
Line 993: Line 976:
HeapPtr dest, HeapPtr source;</syntax>
HeapPtr dest, HeapPtr source;</syntax>


(HeapPtr) <tt>dest:</tt> The string whose end is appended to
(HeapPtr) <tt>dest:</tt> The string whose end is appended to<br>
(HeapPtr) <tt>source:</tt> The string to append
(HeapPtr) <tt>source:</tt> The string to append<br>


Returns: (HeapPtr) dest
Returns: (HeapPtr) dest<br>


This function concatenates two strings on the heap.
This function concatenates two strings on the heap.
Line 1,004: Line 987:
HeapPtr foo, HeapPtr bar[, word length];</syntax>
HeapPtr foo, HeapPtr bar[, word length];</syntax>


(HeapPtr) <tt>foo:</tt> The one string to compare
(HeapPtr) <tt>foo:</tt> The one string to compare<br>
(HeapPtr) <tt>bar:</tt> The other string to compare
(HeapPtr) <tt>bar:</tt> The other string to compare<br>
(int) <tt>width:</tt> The maximum number of characters to compare
(int) <tt>width:</tt> The maximum number of characters to compare<br>


Returns: (word) -1 if foo is less than bar, 0 if both are equal, 1 if foo is greater than bar
Returns: (word) -1 if foo is less than bar, 0 if both are equal, 1 if foo is greater than bar<br>


This function simply encapsulates the libc <tt>strcmp</tt>(<tt>char *</tt>, <tt>char *</tt>) and <tt>strncmp</tt>(<tt>char *</tt>, <tt>char *</tt>, <tt>int</tt>) functions.
This function simply encapsulates the libc <tt>strcmp</tt>(<tt>char *</tt>, <tt>char *</tt>) and <tt>strncmp</tt>(<tt>char *</tt>, <tt>char *</tt>, <tt>int</tt>) functions.
Line 1,016: Line 999:
HeapPtr string;</syntax>
HeapPtr string;</syntax>


(HeapPtr) <tt>string:</tt> The string whose length should be calculated
(HeapPtr) <tt>string:</tt> The string whose length should be calculated<br>


Returns: (word) The length of the specified string.
Returns: (word) The length of the specified string<br>


===Kernel function 0x4b: StrCpy(HeapPtr, HeapPtr[, word])===
===Kernel function 0x4b: StrCpy(HeapPtr, HeapPtr[, word])===
Line 1,024: Line 1,007:
HeapPtr dest, HeapPtr src[, word length];</syntax>
HeapPtr dest, HeapPtr src[, word length];</syntax>


(HeapPtr) <tt>dest:</tt> The destination to copy the string to
(HeapPtr) <tt>dest:</tt> The destination to copy the string to<br>
(HeapPtr) <tt>src:</tt> The source from which the string is to be copied
(HeapPtr) <tt>src:</tt> The source from which the string is to be copied<br>
(word) <tt>length:</tt> The maximum length of the string to copy
(word) <tt>length:</tt> The maximum length of the string to copy<br>


Returns: (HeapPtr) dest
Returns: (HeapPtr) dest<br>


Copies a string, plus the trailing <nowiki>\0</nowiki> terminator. The length of the string may be reduced with the optional length parameter. This function simply encapsulates the libc <tt>strcpy</tt>(<tt>char *</tt>, <tt>char *</tt>) and <tt>strncpy</tt>(<tt>char *</tt>, <tt>char *</tt>, <tt>int</tt>) functions.
Copies a string, plus the trailing <nowiki>\0</nowiki> terminator. The length of the string may be reduced with the optional length parameter. This function simply encapsulates the libc <tt>strcpy</tt>(<tt>char *</tt>, <tt>char *</tt>) and <tt>strncpy</tt>(<tt>char *</tt>, <tt>char *</tt>, <tt>int</tt>) functions.
Line 1,036: Line 1,019:
HeapPtr dest, String format, parameters...;</syntax>
HeapPtr dest, String format, parameters...;</syntax>


(HeapPtr) <tt>dest:</tt> The heap destination to write to
(HeapPtr) <tt>dest:</tt> The heap destination to write to<br>
(String) <tt>format:</tt> The format to use
(String) <tt>format:</tt> The format to use<br>
(misc) <tt>parameters:</tt> The values and strings to insert
(misc) <tt>parameters:</tt> The values and strings to insert<br>


Returns: (HeapPtr) dest
Returns: (HeapPtr) dest<br>


This syscall acts as a frontend to the libc <tt>sprintf</tt>(<tt>char *</tt>, <tt>char *</tt>) function.
This syscall acts as a frontend to the libc <tt>sprintf</tt>(<tt>char *</tt>, <tt>char *</tt>) function.
=== Kernel function 0x4d: GetFarText(word, word, HeapPtr) ===
<syntax type="C">kfunct 0x4d: GetFarText();
word resnr, word stringnr, HeapPtr dest;</syntax>
(word) <tt>resnr</tt>: Number of the text resource to retreive the text from<br>
(word) <tt>stringnr</tt>: Number of the string inside the resource to retreive<br>
(HeapPtr) <tt>dest</tt>: The destination to write the text to<br>
Returns: (HeapPtr) dest<br>
Retrieves a string from a text resource and puts it on the heap.
===Kernel function 0x4e: ReadNumber(HeapPtr)===
<syntax type="C">kfunct 0x4e: ReadNumber();
HeapPtr src;</syntax>
(HeapPtr) <tt>src</tt>: The address of the string to interpret as a number<br>
Returns: (word) The numeric value of the supplied string<br>
This function acts as a frontend to the libc <tt>atoi(char *)</tt> function, with one exception: Numbers beginning with a '$' are interpreted as hexadecimal numbers.
===Kernel function 0x4f: BaseSetter(HeapPtr)===
<syntax type="C">kfunct 0x4f: BaseSetter();
HeapPtr view_obj;</syntax>
(HeapPtr) <tt>view_obj</tt>: The view object whose base is to be set<br>
Returns: (void)<br>
This method is used to set the bounding rectangle of a view. The bounding rectangle is specified by the set {<tt>brLeft</tt>, <tt>brRight</tt>, <tt>brTop</tt>, <tt>brBottom</tt>} of selectors, which indicate the window-relative boundary points of the object's bounding rectangle. The rectangle defined here is used for colission detection, among other things.
The algorithm employed by FreeSCI to determine these values appears to be either identical or very close to the original algorithm; it depends several of the object's selectors (x, y, z, ystep, view) the width and height of the view indicated by its (view, loop, cel) selectors, and that view's horizontal and vertical pixel offset modifyers (xmod, ymod). The algorithm works as follows:
<syntax type="pascal">brLeft := x - xmod - width / 2
brRight := brLeft + width
brBottom := y - z - ymod + 1
brTop := brBottom - ystep</syntax>
===Kernel function 0x50: DirLoop(HeapPtr, word)===
<syntax type="C">kfunct 0x50: DirLoop();
HeapPtr object, word angle;</syntax>
(HeapPtr) <tt>object:</tt> The object whose loop selector is to be set<br>
(word) <tt>angle:</tt> The angle which is to be used as a base to choose the loop angle<br>
Returns: (void)<br>
This function sets the loop selector of the specified object to a value implied by the 'angle' parameter, according to the following table:
{| border="1"
|'''angle'''
|'''loop value'''
|----
|angle &lt; 45 <nowiki>||</nowiki> angle &gt;= 314
|3
|----
|angle &gt;= 45 &amp;&amp; angle &lt; 135
|0
|----
|angle &gt;= 135 &amp;&amp; angle &lt; 225
|2
|----
|angle &gt;= 225 &amp;&amp; angle &lt; 314
|1
|----
|}
===Kernel function 0x51: CanBeHere(HeapPtr [, DblList])===
<syntax type="C">kfunct 0x51: CanBeHere();
HeapPtr obj [, DblList clip_list];</syntax>
(HeapPtr) obj: The object to test<br>
(DblList) cliplist: An optional list of objects to test ''obj ''against Returns: (int) 1 if ''obj ''can be where it is, 0 if not<br>
This function first retreives ''obj’s ''signal and illegalBits selectors, plus its brRect (boundary rectangle, consisting of brTop, brBottom, brLeft and brRight). If either of the DONT_RESTORE or IGNORE_ACTOR flags is set, the function returns 1, otherwise it proceeds with verifying that.
illegalBits bitwise-AND the disjunction of all elements of [[image:math1.png]] a pixel with the color value <tt>n</tt> inside the control map zone delimited by obj's.
[[image:math2.png]]<br>
If both conditions are met, 1 is returned. Otherwise, 0 is returned.
===Kernel function 0x52: OnControl(word, Point | Rect)===
<syntax type="C">kfunct 0x52: OnControl();
word map, Point|Rect area;</syntax>
(word) <tt>map</tt>: The map to check (bit 0: visual, bit 1: priority, bit 2: special)<br>
(Point) or (Rect) Area: The point or rectangle that is to be scanned<br>
Returns: (word) The resulting bitfield<br>
This function scans the indicated point or area on the specified map, and sets the bit corresponding to each color value found correspondingly. For example, if scanning map 4 (special) would touch two areas, one with color value 1 and one with color value 10, the resulting return value would be 0x0402 (binary 0000010000000010).
See also "[[SCI/Specifications/Graphics/Pictures and movement control|Pictures and movement control]] section.
===Kernel function 0x53: InitBresen(HeapPtr [, word])===
<syntax type="C">kfunct 0x53: InitBresen();
HeapPtr mover, word step_factor;</syntax>
(HeapPtr) <tt>mover</tt>: The mover object to initialize<br>
(word) <tt>step_factor</tt>: A factor to multiply the step size with (defaults to 1)<br>
Returns: (void)<br>
Initializes a mover object for bresenham movement from the object's client's coordinates to the coordinates specified by its own pair of (x,y) selectors. To do this, it retreives the mover's client, and calculates the result values according to the algorithm for determining the initial values for iterative line drawing according to the Bresenham line algorithm:
(''the following code is pseudocode Pascal using `::' notation for field access'')
<syntax type=Pascal>
        client := mover::client
        dx := mover::x - client::x
        dy := mover::y - client::y
        vxmax := client::xStep * step_factor
        vymax := client::yStep * step_factor
        numstepsx := |dx / vxmax|
        numstepsy := |dy / vymax|
        IF numstepsx > numstepsy THEN
                numsteps := numstepsx
                mover::b_xAxis := 1
                d0 := dx
                d1 := dy
                s := client::yStep
        ELSE
                numsteps := numstepsy
                mover::b_xAxis := 0
                d1 := dx
                d0 := dy
                s := client::xStep
        FI
        mover::dx := dx / numsteps
        mover::dy := dy / numsteps
        mover::b_di := - |d0|
        mover::b_i1 := 2 * (|d1| - |s * numsteps|) * |d0|
        mover::b_incr := d1 / |d1|
        mover::b_i2 := mover::b_d1 * 2
</syntax>
===Kernel function 0x54: DoBresen()===
<syntax type="C">kfunct 0x55: DoBresen();
; Returns: (void)</syntax>
Executes the Bresenham algorithm on the values calculated by InitBresen, and counts down the number of steps. It then invokes CanBeHere() on the resulting coordinates, and sets the new coordinates if it actually Can Be There.
===Kernel function 0x55: DoAvoider(HeapPtr)===
<syntax type="C">kfunct 0x55: DoAvoider();
HeapPtr avoider;</syntax>
Returns: (word) New direction<br>
This function is a no-op in later SCI games, but is implemented in some or all pre-0.000.576 interpreters.
===Kernel function 0x56: SetJump(?)===
===Kernel function 0x57: SetDebug()===
<syntax type="C">kfunct 0x57: SetDebug();</syntax>
Returns: (void)<br>
This function forces the interpreter to enter debug mode. It is equivalent to pressing LShift-RShift-PadMinus.
===Kernel function 0x58: InspectObj(?)===
===Kernel function 0x59: ShowSends(?)===
===Kernel function 0x5a: ShowObjs(?)===
===Kernel function 0x5b: ShowFree(?)===
===Kernel function 0x5c: MemoryInfo(word)===
<syntax type="C">kfunct 0x5c: word mode();
word mode;</syntax>
(word) <tt>mode</tt>: 0 to 4 (see below)<br>
Returns: (word) The amount of free memory on the heap, in bytes<br>
This function returns the total amount of free memory on the heap if mode == 0. If mode equals 1, the total size of the largest chunk of heap memory is returned. In mode 2, the size of the largest available hunk memory block is returned, and mode 3 returns the total amount of free hunk memory, shiftet to the right by 4 bits.
Mode 4 was apparently introduced in SCI01 and reports the amount of free memory provided by DOS in paragraphs.
===Kernel function 0x5d: StackUsage(?)===
===Kernel function 0x5e: Profiler(?)===
===Kernel function 0x5f: GetMenu(word, word)===
;Parameters:
:entry :'''word''' A pair of bytes. In LE notation, the higher byte is the ``menu ID'', and the lower byte is the ``entry ID''.
:key :'''word''' Special key selecting some particular information regarding the menu entry.
Retrieves some metainformation about an (existing) menu entry. entry selects the menu and entry the information is recovered with respect to, and key specifies which particular information to recover. At the moment, the following kinds of information are known for key:
{|  CELLPADDING=3 BORDER="1"
!  ALIGN="LEFT" | <B>ID</B>
!  ALIGN="LEFT" VALIGN="TOP" WIDTH=99 | <B>FreeSCI macro (<TT>MENU_ATTRIBUTE_</TT>...)</B>
!  ALIGN="LEFT" VALIGN="TOP" WIDTH=269 | <B>Description</B>
|-
|  ALIGN="LEFT" | 0x6d
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=99 | <TT>SAID</TT>
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=269 | The ``<I>Said</I>'' spec associated with the menu entry, or a null pointer. If this spec is matched, the next <TT>GetEvent()</TT> call will behave as if the appropriate menu option had been selected.
|-
|  ALIGN="LEFT" | 0x6e
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=99 | <TT>TEXT</TT>
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=269 | The string currently displayed for the menu item.
|-
|  ALIGN="LEFT" | 0x6f
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=99 | <TT>KEY</TT>
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=269 | An optional key (as reported by <TT>GetKey()</TT>) the menu option should be triggered by.
|-
|  ALIGN="LEFT" | 0x70
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=99 | <TT>ENABLED</TT>
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=269 | Whether the menu option is enabled or not (in the latter case, it is grayed out and cannot be selected).
|-
|  ALIGN="LEFT" | 0x71
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=99 | <TT>TAG</TT>
|  ALIGN="LEFT" VALIGN="TOP" WIDTH=269 | A value without special semantics.
|}
===Kernel function 0x60: SetMenu(word, [word, any]*)===
;Parameters:
:entry : '''word''' A pair of bytes. In LE notation, the higher byte is the ``menu ID'', and the lower byte is the ``entry ID''.
:key : '''word''' A special key selecting some particular information regarding the menu entry.
:value : '''word''' A special key selecting some particular information regarding the menu entry.
<tt>SetMenu</tt> is a varargs function; it takes a menu bar <tt>entry</tt> ID (cf. <tt>GetMenu</tt>, section Kernel function 0x5f) followed by any even number of parameters. Each of these parameter pairs begins with a <tt>key</tt>; the second entry is a <tt>value</tt> whose type depends on the key. Semantics of <tt>key</tt> are as in <tt>GetMenu</tt> (cf. section Getmenu).
===Kernel function 0x61: GetSaveFiles(String, String, HeapPtr*)===
<syntax type="C">kfunct 0x61: GetSaveFiles();
String game_id, String strspace, HeapPtr *ptrs;</syntax>
(String) <tt>game_id</tt>: The game ID as a string<br>
(String) <tt>strspace</tt>: The string which the result should be stored in<br>
(HeapPtr *) <tt>ptrs</tt>: The array of pointers which the string pointers are to be stored in<br>
Returns: (word) The number of savegames for the specified game_id<br>
Returns an array of strings describing the existing save games for game_id. The strings are put into strspace one by one, and heap pointers to each of them are put into the ptrs array. The number of saved games is returned in the accumulator.
===Kernel function 0x62: GetCWD(HeapPtr)===
<syntax type="C">kfunct 0x62: GetCWD();
HeapPtr address;</syntax>
(HeapPtr) <tt>address</tt>: The address to write to<br>
Returns: (HeapPtr) The supplied address<br>
This function retrieves the current working directory (CWD) and stores its string representation at the location pointed to by the supplied parameter.
FreeSCI returns a sub-directory of the user's home directory, if applicable, instead of the cwd.
===Kernel function 0x63: CheckFreeSpace(String)===
<syntax type="C">kfunct 0x63: CheckFreeSpace();
String path;</syntax>
(String) <tt>path</tt>: The path to examine<br>
Returns: (word) 1 if saving is possible, 0 otherwise<br>
Returns TRUE if there would be enough space left on the specified path to save the current game (but doesn't actually save).
===Kernel function 0x64: ValidPath(?)===
===Kernel function 0x65: CoordPri(?)===
===Kernel function 0x66: StrAt (String, word[, char])===
<syntax type="C">kfunct 0x66: StrAt();
String src, word offset[, char replacement];</syntax>
(String) <tt>src</tt>: The string to read from<br>
(word) <tt>offset</tt>: The offset inside the string<br>
(char) <tt>replacement</tt>: An optional replacement value for the indexed character<br>
Returns: (char) The character requested<br>
This function retreives a single character from a string. Optionally, if <tt>replacement</tt> is set, the source character will be replaced with the specified <tt>replacement</tt>.
===Kernel function 0x67: DeviceInfo(word, String[, String])===
<syntax type="C">kfunct 0x67: DeviceInfo();
word sub_function, String string1[, String string2];</syntax>
(word) <tt>sub_function</tt>: A numeric value from 0 to 3, inclusive. See below<br>
(String) <tt>string1</tt>: See below<br>
(String) <tt>string2</tt>: See below<br>
Returns: See below<br>
Depending on the value of sub_function, this system call executes one of four defined actions:
<ol type="0" start=0>
<li>GET_DEVICE
<li>GET_CURRENT_DEVICE
<li>PATHS_EQUAL
<li>IS_FLOPPY
</ol>
See the specific function definitions below for more information.
===Kernel function 0x67: DeviceInfo(GET_DEVICE, String, String)===
<syntax type="C">kfunct 0x67: DeviceInfo();
word GET_DEVICE, String input, String output;</syntax>
(word) <tt>GET_DEVICE</tt>: Constant sub-function identifier (0)<br>
(String) <tt>input</tt>: A path whose device identifier should be extracted<br>
(String) <tt>output</tt>: The destination of the device identifier<br>
Returns: (HeapPtr) Points to the terminating zero character of output<br>
GET_DEVICE returns the drive/device on which "input" resides in output (and a pointer to the terminating NULL in the accumulator).
===Kernel function 0x67: DeviceInfo(GET_CURRENT_DEVICE, String output)===
<syntax type="C">kfunct 0x67: DeviceInfo();
word GET_CURRENT_DEVICE, String output;</syntax>
(word) <tt>GET_CURRENT_DEVICE</tt>: Constant sub-function identifier (1)<br>
(String) <tt>output</tt>: The destination which the CWD device identifier should be written to<br>
Returns: (HeapPtr) Points to the terminating null character of output<br>
GET_CURRENT_DEVICE returns the drive/device that contains the current working directory (and a pointer to the terminating NULL in the accumulator).
===Kernel function 0x67: DeviceInfo(PATHS_EQUAL, String path1, String path2)===
<syntax type="C">kfunct 0x67: DeviceInfo();
word PATHS_EQUAL, String path1, String path2;</syntax>
(word) <tt>PATHS_EQUAL</tt>: Constant sub-function identifier (2)<br>
(String) <tt>path1</tt>: First path to compare<br>
(String) <tt>path2</tt>: Second path to compare<br>
Returns: (word) 1 if path1 and path2 point to the same physical location, 0 otherwise<br>
PATHS_EQUAL returns TRUE if the two supplied paths point to the same place.
===Kernel function 0x67: DeviceInfo(IS_FLOPPY, String path)===
<syntax type="C">kfunct 0x67: DeviceInfo();
word IS_FLOPPY, String path;</syntax>
(word) <tt>IS_FLOPPY</tt>: Constant sub-function identifier (3)<br>
(String) <tt>path</tt>:<br>
Returns: (word) 1 if <tt>path</tt> is on a floppy disk, 0 otherwise<br>
PATHS_EQUAL returns TRUE if the two supplied paths point to the same place.
===Kernel function 0x68: GetSaveDir()===
<syntax type="C">kfunct 0x68: GetSaveDir();</syntax>
Returns: (String)<br>
This function returns the heap position allocated to store the string representation of the save game directory. This heap space is allocated automatically during startup.
===Kernel function 0x69: CheckSaveGame(String, word[, String])===
<syntax type="C">kfunct 0x69: CheckSaveGame();
String game_id, word game_nr[, String version];</syntax>
(String) <tt>game_id</tt>: The savegame ID string<br>
(word) <tt>game_nr</tt>: The savegame number<br>
(String) <tt>version</tt>: An optional game version string<br>
Returns: (word) 1 if the savegame is loadable, 0 otherwise<br>
Returns TRUE if the specified save game is valid and loadable (i.e., not for another game/interpreter/version).
===Kernel function 0x6a: ShakeScreen(word[, word])===
<syntax type="C">kfunct 0x6a: ShakeScreen();
word times [, word direction];</syntax>
(word) <tt>times</tt>: Number of times to shake the screen<br>
(word) <tt>direction</tt>: See below<br>
Returns: (void)<br>
If <tt>direction</tt> is not specified, it defaults to 1. It is a bitmask and defined as follows:
* bit 0 Shake 10 pixels downwards
* bit 1 Shake to the right
* bit 2 Unknown, but used
===Kernel function 0x6b: FlushResources(?)===
===Kernel function 0x6c: SinMult(?)===
===Kernel function 0x6d: CosMult(?)===
===Kernel function 0x6e: SinDiv(?)===
===Kernel function 0x6f: CosDiv(?)===
===Kernel function 0x70: Graph(?)===
===Kernel function 0x71: Joystick(word, word)===
<syntax type="C">kfunct 0x71: Joystick();
word subfunction, word param;</syntax>
(word) <tt>subfunction</tt>: Always 0x0c<br>
(word) <tt>param</tt>: Parameter for the subfunction, purpose unknown<br>
Returns: (void)<br>

Latest revision as of 16:06, 18 August 2024

Kernel functions

Acknowledgements for this section go to Lars Skovlund, Francois Boyer and Jeremy Tartaglia for providing additional information.

In SCI0, calls to the SCI kernel are initiated by using the callk opcode. callk has the opcode 0x42 or 0x43; 0x42 takes one 16 bit little endian and one 8 bit parameter, 0x43 takes two 8 bit parameters. The first parameter is the number of the kernel function to be called, the second number undetermined (as of yet).

Opcode summary:

op 0x42: callk W kfunct, B kparams (4 bytes)
op 0x43: callk B kfunct, B kparams (3 bytes)

The number of parameters passed to the kernel function are determined by kparam. A total number of (kparams+2) bytes are removed from the local stack and passed on to the kernel function. The first two of those bytes are apparently always created by pushing the number of following bytes. For example, if Load(view, 10) is called, then we've got two word parameters, "view" (0x0080) and "10" (0x000a). So the callk function would have kparams set to 4; this value would be pushed to the stack first, followed by the two parameters. So the stack would look like this (left means lower address, byte ordering little endian):

02 00 80 00 0a 00

before calling Load().

Return values are returned into the accumulator, unless stated otherwise. If return type is stated as (void), then the accumulator is not modified.

Parameter types

SCI0 uses only little endian 16 bit integer values for parameters. However, this document distinguishes between different uses of those integers by defining the following variable types:

(word)
16 bit signed little endian integer
(HeapPtr)
As (word); interpreted as a pointer to a heap address
(DblList)
As (HeapPtr); interpreted as offset of a doubly linked list
(Node)
As (HeapPtr); interpreted as offset of a list node
(&FarPtr)
As (HeapPtr); interpreted as the 32 bit pointer stored at the referenced heap address
(Point)
A sequence of two (word)s to describe a point on the screen, with the y coordinate being the first in the sequence.
(Rect)
A sequence of four (word)s describing a rectangle. If you read "(Rect) foo", think "(word) foo_ymin, (word) foo_xmin, (word) foo_ymax, (word) foo_xmax" instead.
(String)
If greater than or equal to 1000, this is the heap address of a text string. If less than 1000, it is the number of a text resource, and immediately followed by another word that contains the number of the string inside the text resource.

Parameters in brackets (like "[foo]") are optional.

Most functions exit gracefully if either a NULL HeapPtr or DblList is provided.

SCI0 Kernel functions

Kernel function 0x00: Load(word, word)

<syntax type="C">kfunct 0x00: Load(); word ResType, word ResNr;</syntax>

(word) ResType: The resource type number | 0x80 (as in the patch files)
(word) ResNr: The resource number

Returns: (&FarPtr): A HeapPtr pointing to an actual pointer on the heap.

Loads a resource. The returned HeapPtr points to a special point on the heap where a pointer (32 bits) to the memory location of the specified resource is located. If the resource type equals sci_memory, the resource number is interpreted as a memory size instead; the specified number of bytes is allocated dynamically, and a handle returned.

Kernel function 0x01: UnLoad(word, word)

<syntax type="C">kfunct 0x01: UnLoad(); word ResType, word ResNr;</syntax>

(word) ResType: The resource type number | 0x80
(word) ResNr: The resource number

Returns: (void)

This function unloads a resource identified by its ResType and ResNr, NOT by the HeapPtr it has been loaded to, except for sci_memory resources, where the parameters are the memory resource type and the handle.

Kernel function 0x02:ScriptID(word, word)

<syntax type="C">kfunct 0x02: ScriptID(); word ScriptNr, word DispatchNr;</syntax>

(word) ScriptNr: Number of the script to reference
(word) DispatchNr: Number of the Dispatch entry inside the script to reference

Returns: (HeapPtr): The address pointed to by the specified element of the dispatch/exports table (script block type #7).

This function returns the address pointed to by an element of a script's dispatch table.

Kernel function 0x03: DisposeScript(word ScriptNumber)

<syntax type="C">kfunct 0x03: DisposeScript(); word ScriptNumber;</syntax>

(word) ScriptNumber

Returns: (void)

Disposes a script. Unloads it, removes its entries from the class table, and frees the associated heap memory.

Kernel function 0x04: Clone(HeapPtr)

<syntax type="C">kfunct 0x04:Clone(); HeapPtr object;</syntax>

(HeapPtr) object: The object to clone

Returns: (HeapPtr) The address of the clone

This function clones a Class or Object by copying it as a whole and mofifying the -info- selector so that it contains 1. Objects with -info- set to 0x8000 (Classes) are stripped of their selector name area, and both Objects and Classes are stripped of the function selector area.

Kernel function 0x05: DisposeClone(HeapPtr)

<syntax type="C">kfunct 0x05: DisposeClone(); HeapPtr clone;</syntax>

(HeapPtr) clone: The clone to dispose

Returns: (void)

Frees all memory associated with a cloned object (as produced by Clone()).

Kernel function 0x06: IsObject(HeapPtr)

<syntax type="C">kfunct 0x06: IsObject(); HeapPtr suspected_object;</syntax>

(HeapPtr) suspected_object: The address of something that is suspected to be an object.

Returns: (int) 1 if there is an object at the specified address, 0 if not.

This function checks whether the supplied heap pointer is valid and returns 0 if not, then proceeds to testing whether an object is at the indexed heap position. If it is, 1 is returned, 0 otherwise.

Kernel function 0x07: RespondsTo(?)

Kernel function 0x08: DrawPic(word[, word, word, word]) KDrawPickfunct 0x08: DrawPic(); word PicNr[, word Animation, word Flags, word DefaultPalette];

(word) PicNr: The resource number of the picture to draw
(word) Animation: One of the following animation modes:

  1. Display instantly
  2. horizontally open from center
  3. vertically open from center
  4. open from right
  5. open from left
  6. open from bottom
  7. open from top
  8. open from edges to center
  9. open from center to edges
  10. open random checkboard
  11. horizontally close to center, reopen from center
  12. vertically close to center, reopen from center
  13. close to right, reopen from right
  14. close to left, reopen from left
  15. close to bottom, reopen from bottom
  16. close to top, reopen from top
  17. close from center to edges, reopen from edges to center
  18. close from edges to center, reopen from center to edges
  19. close random checkboard, reopen

The animation is executed when kAnimate() (see (see Views and animation in SCI section) is invoked. If not specified, it is assumed to be the same animation as last time. (word) Flags:

  • Bit 0: Clear screen before drawing
  • Bit 1-f: unknown, probably unused

If not specified, it defaults to 1.

Some interpreter versions older than 0.000.502 interpret this parameter inversely, and have 0 as a default.

(word) DefaultPalette: The default palette number to use for drawing

Returns: (void)

The second parameter does not appear to affect anything. In QfG1, it appears to be set to 0x64 constantly. DefaultPalette is used to differentiate between day and night in QfG1. Palette 1 is used for "night" pictures, Palette 0 for "day" pictures there. The picture is drawn to the background image (which is used for restauration of everything with the exception of the mouse pointer). To bring it to the foreground, Animate() must be used.

Kernel function 0x09: Show()

<syntax type="C">kfunct 0x09: Show();

Returns
(void)</syntax>

Sets the PicNotValid flag to 2.

Kernel function 0x0a: PicNotValid([word])

<syntax type="C">kfunct 0x0a: PicNotValid(); [(word) NewPicNotValid];</syntax>

[(word) NewPicNotValid]: The new value of the "PicNotValid" flag.

Returns: (word): The previous value of the "PicNotValid" flag

This sets the PicNotValid flag that determines whether or not the current background picture should be considered "valid" by the other kernel functions.

Kernel function 0x0b: Animate([DblList], [word])

<syntax type="C">KAnimatekfunct 0x0b: Animate(); [DblList ViewList], [word cycle];</syntax>

[(DblList) ViewList]: List of views that are to be drawn on top of the background picture
(word) <unknown>

Returns: (void)

This function draws a background picture plus some views to the foreground. If the background picture had not been drawn previously, it is animated with the animation style set during kDrawPic (see section Kernel function 0x08). Drawing the views is a rather complex issue. Refer to Views and animation in SCI section for its description.

Kernel function 0x0c: SetNowSeen(DblList)

<syntax type="C">?? kfunct 0x0c: SetNowSeen(); DblList ViewList;</syntax>

(DblList) ViewList: List of affected views

Returns: (void)

Kernel function 0x0d: NumLoops(HeapPtr)

<syntax type="C">kfunct 0x0d: NumLoops(); HeapPtr object;</syntax>

(HeapPtr) object: The object which the view selector should be taken from

Returns: (word) The number of loops in the view

This function looks up the view selector in the specified object, loads the view resource associated with it, and checks for the number of animation loops in the view.

Kernel function 0x0e: NumCels(HeapPtr)

<syntax type="C">kfunct 0x0e: NumCels(); HeapPtr object;</syntax>

HeapPtr object: The object which the selectors should be taken from

Returns: (word) The number of cels in the loop

This function looks up one specific loop in a specific view (both are taken from selectors with the same name from the object pointed to by the parameter) and returns the number of cels (animation frames) in it.

Kernel function 0x0f: CelWide(word view, word loop, word cel)

<syntax type="C">kfunct 0x0f: CelWide(); word view, word loop, word cel;</syntax>

(HeapPtr) view: The view we're searching in loop: The loop the cel is contained in cel: The cel we're interested in

Returns: (word) The width of the cel identified by the tuple (view, loop, cel).


Kernel function 0x11: DrawCel(word, word, word, Point, word)

<syntax type="C">kfunct 0x11: DrawCel(); word view, word loop, word cel, Point pos, word priority;</syntax>

(word) view: Number of the view resource to display
(word) loop: Number of the loop in the view resource to display
(word) cel: Number of the cel inside the loop to display
(Point) pos: Position the cel should be drawn to
(word) priority: Priority to draw the cel with

Returns: (void)

Explicitly draws a cel, specified by the complete tuple (view, loop, cel), to a specified position. Invalid loop/cel values are assumed to be 0.

Kernel function 0x12: AddToPic(DblList)

<syntax type="C">kfunct 0x12: AddToPic(); DblList picviews;</syntax>

(DblList) picviews: A doubly linked list of PicViews, i.e. objects that are drawn statically onto the background picture

Returns: (void)

This function stores the list of PicViews for later use by the Animate() syscall. See Kernel function 0x0b section for more details.

Kernel function 0x13: NewWindow(Rect, HeapPtr, word, word, word, word)

<syntax type="C">KNewWindowkfunct NewWindow(); Rect Boundaries, HeapPtr Title, word Flags, word Priority, word FGColor, word BGColor;</syntax>

(Rect) Boundaries: The bounding rectangle of the window
(HeapPtr) Title: A pointer to the window title
(word) Flags:

  • bit 0 - transparency
  • bit 1 - window does not have a frame
  • bit 2 - the window has a title (starting 10 pixels above the minimum y position specified as the first element of Boundaries)
  • bit 3-6 - unused
  • bit 7 - don't draw anything

(word) Priority: The priority at which the window should be drawn, or -1 to force on-top drawing
(word) FGColor: The foreground color for the window
(word) BGColor: The background color

Returns: (HeapPtr): The position of the window structure on the heap

This function creates a window (see also Windows, Dialogs and Controls section), sets this window as the active port, draws the window (if neccessary), and returns with the window's heap address.

Kernel function 0x14: GetPort()

<syntax type="C">KGetPortkfunct 0x14: GetPort();</syntax>

Returns
(HeapPtr): A pointer to a record with the internal representation of the currently active port.

Returns a heap pointer to a port structure.

Kernel function 0x15: SetPort()

<syntax type="C">KSetPortkfunct 0x15: SetPort(); HeapPtr NewPort;</syntax>

(HeapPtr) NewPort: The new port to set

Returns: (void)

This selects the new port which many kernel functions will draw to.

If 0 is passed, the window manager port is selected. The picture window is not accessible using this call. Only other kernel calls like KDrawPic may activate the picture window - and they always save the old port and restore it before they return.

Kernel function 0x16: DisposeWindow(HeapPtr Window)

<syntax type="C">KDisposeWindowkfunct 0x16: DisposeWindow(); HeapPtr Window;</syntax>

(HeapPtr) Window: The heap address of the window to destroy

Returns: (void)

Destroys a window and frees the associated heap structure.

Kernel function 0x17: DrawControl(HeapPtr)

<syntax type="C">KDrawControlkfunct 0x17: DrawControl(); HeapPtr Control;</syntax>

(HeapPtr) Control: The heap address of the Control to draw

Returns: (void)

This function draws a Control (see Windows, Dialogs and Controls section for details). Please note that the correct port must be selected beforehand.

Kernel function 0x18: HiliteControl(HeapPtr)

<syntax type="C">KHiliteControlkfunct 0x18: HiliteControl(); HeapPtr Control;</syntax>

(HeapPtr) Control: The control to highlight

Returns: (void)

This function is used to highlight a control by drawing it with an inverted color scheme. It requires the correct port to be set beforehand. See Windows, Dialogs and Controls section for details on the windowing Control system.

Kernel function 0x19: EditControl(HeapPtr)

<syntax type="C">KEditControlkfunct 0x19: EditControl(); HeapPtr Control, HeapPtr Event;</syntax>

(HeapPtr) Control: A heap pointer to the Control to edit
(HeapPtr) Event: The event to interpret

Returns: (void)

This function will apply the event provided to edit a type 3 (Edit window) Control (see Windows, Dialogs and Controls section for a description of the control system). Normal keypresses are added to the area pointed to by Control::text, unless the total string length would be greater than Control::max. Cursor keys, backspace and a few other keys may be used to manipulate the control. In FreeSCI, some of the libreadline control keys can be used to edit and move the cursor as well. If it is called to edit a Control which is not of type 3, it returns without error. Please note that the correct port (usually the window which the Control was drawn in) must be selected beforehand.

Kernel function 0x1a: TextSize(HeapPtr, HeapPtr, word[, word])

<syntax type="C">kfunct 0x1a: TextSize(); HeapPtr dest, HeapPtr src, word font[, word maxwidth];</syntax>

(HeapPtr) dest: The destination to write the rectangle to
(HeapPtr) src: A pointer to the string to analyze
(word) font: The number of the font resource to use for this check
(word) maxwidth: The maximum width to allow for the text (defaults to 192)

Returns: (void)

This function calculates the width and height the specified text will require to be displayed with the specified font and the specified maximum width. The result will be written to the (you guessed it) specified destination on the heap. The result is a rectangle structure: The first four bytes equal to zero, the next word is the height, and the last word is the width.

Kernel function 0x1b: Display(String, word...)

<syntax type="C">kfunct 0x1b: Display(); String text, word commands...;</syntax>

(String) text: The text to work with
(word) commands...: A sequence of commands with parameters:

  • 100: 2 params, (X,Y) coord of where to write on the port.
  • 101: 1 param, -1, 0 or 1 (align right (-1), left (0) or center (1).
  • 102: 1 param, set the text color.
  • 103: 1 param, set the background color (-1 to draw text with transparent background).
  • 104: 1 param, set the "gray text" flag (1 to draw disabled items).
  • 105: 1 param, (resource number) set the font.
  • 106: 1 param, set the width of the text (the text wraps to fit in that width)
  • 107: no param, set the "save under" flag, to save a copy of the pixels before writing the text (the handle to the saved pixels is returned).
  • 108: 1 param, (handle to stored pixels) restore under. With this command, the text and all other parameters are ignored.

Returns: (void) or (&FarPtr)(see above)

This function executes the specified commands, then draws the supplied text to the active port (unless command 108 was executed).

Kernel function 0x1c: GetEvent(word, HeapPtr)

<syntax type="C">KGetEventkfunct 0x1c: GetEvent(); word Flags, HeapPtr Event;</syntax>

(word) Flags: A bitfield:

  • bit 0 - 14: Bit mask for the events to be returned.
  • bit 15: Disable joystick polling

(HeapPtr) Event: An Object on the stack which the results are written to

Returns: (word): 0 if a null event was created, 1 otherwise

This function fills an Event object with data from the event queue. The results are written to the "type", "message" and "modifiers" selectors. See Event handling in SCI section for details.

Kernel function 0x1d: GlobalToLocal(HeapPtr Event)

<syntax type="C">KGlobalToLocalkfunct 0x1d: GlobalToLocal(); HeapPtr Event;</syntax>

(HeapPtr) Event: pointer to the Event object to convert

Returns: (void)

This function converts a screen-relative event to a port-relative one, using the currently active port.

Kernel function 0x1e: LocalToGlobal(HeapPtr Event)

<syntax type="C">KLocalToGlobalkfunct 0x1e: LocalToGlobal(); HeapPtr Event;</syntax>

(HeapPtr) Event: pointer to the Event object to convert

Returns: (void)

This function converts a port-relative event to a screen-relative one, using the currently active port.

Kernel function 0x1f: MapKeyToDir(HeapPtr Event)

<syntax type="C">KMapKeyToDirkfunct 0x1f: MapKeyToDir(); HeapPtr Event;</syntax>

(HeapPtr) Event: pointer to the Event object to convert

Returns: (HeapPtr): A pointer to the converted object

This function converts a keyboard event to a movement event, if possible. Otherwise, the function returns without error. See Event handling in SCI section for details.

Kernel function 0x20: DrawMenuBar(word)

<syntax type="C">kfunct 0x20: DrawMenuBar(); word mode;</syntax>

(word) mode: 1 to draw, 0 to clear

Returns: (void)

Either draws or clears (overdraws with black) the menu bar.

Kernel function 0x21: MenuSelect(HeapPtr[, word])

<syntax type="C">kfunct 0x21: MenuSelect(); HeapPtr event[, word flag];</syntax>

(HeapPtr) event: The event to interpret
(word) flag: (unknown)

Returns: (word) The menu index of a selected option, -1 if no menu option was selected, or 0 if the event passed through all of the menu system's filters.

This function interprets the event passed to it by running several checks. First, it tries to determine whether the menu system was activated by pressing the ESC key or clicking on the menu bar. In this case, the interpreter takes over and waits for the player to select a menu option. It then returns the menu option selected (menu number, starting at 1, in the upper 8 bits, item number, starting at 1 as well, in the lower part) or -1 if no active menu item was selected. In any case, the event is claimed. If the menu system was not activated by the event, it checks the event against the key commands or Said Blocks associated with each menu entry. If there is a match, the menu coordinate tuple is returned and the event is claimed, otherwise, 0 is returned.

Kernel function 0x22: AddMenu(HeapPtr, HeapPtr)

<syntax type="C">kfunct 0x22: AddMenu(); HeapPtr title, HeapPtr content;</syntax>

(HeapPtr) title: The menu title
(HeapPtr) content: The menu options

Returns: (void)

This function adds a menu to the menu bar. The menu title is passed in the first parameter, the second parameter contains a heap pointer to the menu entries. They are contained in one single string; the following special characters/character combinations are used:

  • ’‘’:<nowiki> Right justify the following text * <nowiki>’:’:<nowiki> Menu item separator * <nowiki>”–!”:<nowiki> Seperation line: This menu item is just a separator * <nowiki>’#’:<nowiki> Function key. This is replaced by an F for displaying * <nowiki>’ˆ’:<nowiki> Control key. This is replaced by <nowiki>\001 (CTRL) for displaying

Kernel function 0x23: DrawStatus(HeapPtr)

<syntax type="C">kfunct 0x23: DrawStatus(); HeapPtr text;</syntax>

(HeapPtr) text: The text to draw

Returns: (void)

Draws the specified text to the title bar.

Kernel function 0x24: Parse(HeapPtr, HeapPtr)

kfunct 0x24: Parse(); HeapPtr event, HeapPtr input;

(HeapPtr) event: The event to generate
(HeapPtr) input: The input line to parse

Returns: (word) 1 on success, 0 otherwise

This function parses the input line and generates a parse event (type 0x80). See The Parser and Event handling in SCI sections for details.

Kernel function 0x25: Said(HeapPtr)

<syntax type="C">kfunct 0x:25: Said(); HeapPtr said_block;</syntax>

(HeapPtr) said_block: Pointer to a Said block

Returns: (word) 1 if the line last parsed meets the criteria of the supplied said_block, 0 otherwise.

This function is only invoked after Parse() was called, and works on output generated by this function. See The Parser and Event handling in SCI sections for details.

Kernel function 0x26: SetSynonyms(DblList)

<syntax type="C">kfunct 0x26: SetSynonyms(); HeapPtr list;</syntax>

(DblList) list: List of script objects to examine

Returns: (void)

This function sets the synonyms used by the parser. Synonyms are used to replace specified word groups with other word groups. The list contains a collection of script objects; all synonyms defined by the corresponding script (which can be identified by evaluating the 'number' selector of the script object) are added to the list of active synonyms.

Kernel function 0x27: HaveMouse()

<syntax type="C">kfunct 0x27: HaveMouse();</syntax>

Returns: (word) 1 if a mouse is available, 0 if not

This function simply returns a flag containing the availability of a pointing device.

Kernel function 0x28: SetCursor(word, word[, Point])

<syntax type="C">kfunct 0x28: SetCursor(); word resource, word visible[, Point coordinates];</syntax>

(word) resource: The cursor resource to use for drawing the mouse pointer
(word) visible: 1 if the mouse pointer should be visible, 0 if not
(Point) coordinates: The coordinates (relative to the wm-port) to move the mouse pointer to

Returns: (void)

This function can change the appearance and position of the mouse pointer. If no position is provided, the position remains unchanged.

Kernel function 0x29: FOpen(String, word)

<syntax type="C">kfunct 0x29: FOpen(); String fname, word mode;</syntax>

(String) fname: The file name
(word) mode: The mode to open the file with

Returns: (word) a file handle on success, 12#12 on error

Tries to open or create a file in the CWD with the specified file name. The following modes are valid:

  • 0: open or create: Try to open file, create it if it doesn't exist
  • 1: open or fail: Try to open file, abort if not possible
  • 2: create: Create the file, destroying any content it might have had

Kernel function 0x2a: FPuts(word, String)

<syntax type="C">kfunct 0x2a: FPuts(); word filehandle, String data;</syntax>

(word) filehandle: Handle of the file to write to
(String) data: The string to write to the file

Returns: (void)

Writes a zero-terminated string to a file.

Kernel function 0x2b: FGets(String, word, word)

<syntax type="C">kfunct 0x2b: FGets(); String dest, word maxsize, word handle;</syntax>

(String) dest: Pointer to the destination buffer
(word) maxsize: Maximum number of bytes to read
(word) handle: Handle of the file to read from

Returns: (word) The number of bytes actually read

Kernel function 0x2c: FClose(word)

<syntax type="C">kfunct 0x2c: FClose(); word filehandle;</syntax>

(word) filehandle: Handle of the file to close

Returns: (void)

Closes a previously opened file.

Kernel function 0x2d: SaveGame(String, word, String, String)

<syntax type="C">kfunct 0x2d: SaveGame(); String game_id, word save_nr, String save_description, String version;</syntax>

(String) game_id: The game object's ID string (e.g. "SQ3")
(word) save_nr: "slot" the game is to be saved to
(String) save_description: String description of the game
(String) version: Stringified game version number

Returns: (word) 1 on success, 0 if an error occured while saving

This function saves the game state (heap, windows, call stack, view list, sound state etc.) to the savegame with the numeric id save_nr and the description save_description. game_id and version are stored alongside, for verification when the game state is restored.

Kernel function 0x2e: RestoreGame(String, word, String)

<syntax type="C">kfunct 0x2e: RestoreGame(); String game_id, word save_nr, String version;</syntax>

(String) game_id: The game object's ID string
(word) save_nr: Number of the save game to restore
(String) version: The game object's version number

Returns: (void)

This function restores a previously saved game. It should only return if restoring failed.

Kernel function 0x2f: RestartGame()

<syntax type="C">kfunct 0x2f: RestartGame();</syntax> Returns: never

If this function is invoked, the following things happen:

  • The restarting flag is set
  • The menu bar structure is destroyed
  • All sounds are stopped
  • All scripts are removed from the script table
  • The heap status is reset, but the heap is not cleared

After this is done, the engine restarts at a certain point (see Interpreter initialization and the main execution loop section for more details), re-initializes the stack, and executes the replay method of the game object.

Kernel function 0x30: GameIsRestarting()

<syntax type="C">kfunct 0x30: GameIsRestarting();</syntax>

Returns: (word) 1 if the game is restarting, 0 if not

Kernel function 0x31: DoSound(word, ...])

<syntax type="C">kfunct 0x31: DoSound(); word action, ...;</syntax>

(word) action: The sound command subfunction number

Returns: (see below)

'action' may be one of the following:

  • 0x0: INIT
  • 0x1: PLAY
  • 0x2: NOP
  • 0x3: DISPOSE
  • 0x4: SET_SOUND
  • 0x5: STOP
  • 0x6: SUSPEND
  • 0x7: RESUME
  • 0x8: VOLUME
  • 0x9: UPDATE
  • 0xa: FADE
  • 0xb: CHECK_DRIVER
  • 0xc: ALL_STOP

See individual descriptions below for more information.

Kernel function 0x31: DoSound(INIT, Object)

<syntax type="C">kfunct 0x31: DoSound(); word 0, Object sound_obj;</syntax>

(word) 0: subfunction identifier
(Object) sound_obj: The sound object affected

Returns: (void)

Initializes the specified sound object. This will set the 'status' selector of the object to 1 ('initialized'), and load the sound indicated by the 'number' selector into the sound driver.

Kernel function 0x31: DoSound(PLAY, Object)

<syntax type="C">kfunct 0x31: DoSound(); word 1, Object sound_obj;</syntax>

(word) 1: The subfunction identifier
(Object) sound_obj: The sound object affected

Returns: (void)

Starts to play the song represented by the specified sound object. This will also set the 'status' selector of the object to 2 ('playing').

Kernel function 0x31: DoSound(NOP)

<syntax type="C">kfunct 0x31: DoSound(); word 2;</syntax>

(word) 2: The sound command subfunction number

Returns: (void)

No action appears to be associated with this subfunction call.

Kernel function 0x31: DoSound(DISPOSE, Object)

<syntax type="C">kfunct 0x31: DoSound(); word 3, Object sound_obj;</syntax>

(word) 3: The sound command subfunction number
(Object) sound_obj: The sound object affected

Returns: (void)

Removes the song indexed by a sound object from the sound server song list.

Kernel function 0x31: DoSound(SET_SOUND, word)

<syntax type="C">kfunct 0x31: DoSound(); word 4, word state;</syntax>

(word) 4: The sound command subfunction number
(word) state: 1 if sound should be active, 0 if it should be turned off

Returns: (word) 1 if currently active, 0 if currently muted.

This function completely mutes or un-mutes the sound subsystem. If called with no parameters, it returns the current status.

Kernel function 0x31: DoSound(STOP, Object)

<syntax type="C">kfunct 0x31: DoSound(); word 5, Object sound_obj;</syntax>

(word) 5: The sound command subfunction number
(Object) sound_obj: The sound object affected

Returns: (void)

Stops playing the song represented by the specified sound object. This will set the object's 'state' selector to 0 ('stopped').

Kernel function 0x31: DoSound(SUSPEND, Object)

<syntax type="C">kfunct 0x31: DoSound(); word 6, Object sound_obj;</syntax>

(word) 6: The sound command subfunction number
(Object) sound_obj: The sound object affected

Returns: (void)

Suspends the song associated with the specified sound object. Its state is buffered, so that it can be resumed later on. The sound object's 'state' selector is set to 3 ('suspended').

Kernel function 0x31: DoSound(RESUME, Object)

<syntax type="C">kfunct 0x31: DoSound(); word 7, Object sound_obj;</syntax>

(word) 7: The sound command subfunction number
(Object)
sound_obj:
The sound object affected

Returns: (void)

Resumes a previously suspended song. The 'state' selector is set to 2 ('playing').

Kernel function 0x31: DoSound(VOLUME[, word])

<syntax type="C">kfunct 0x31: DoSound(); word 8[, word volume];</syntax>

(word) 8: The sound command subfunction number
(word) volume: An optional volume parameter

Returns: (word) The currently set sound volume (0 to 0xf)

This subfunction retrieves and returns the current sound volume. If a second parameter is supplied the volume will be set to the value of this parameter.

Kernel function 0x31: DoSound(UPDATE, Object])

<syntax type="C">kfunct 0x31: DoSound(); word 9, Object sound_obj;</syntax>

(word) 9: The sound command subfunction number
(Object) sound_obj: The sound object affected

Returns: (void)

Notifies the sound server that a sound object was modified. The song priority and number of loops (stored in the 'priority' and 'loop' selectors, respectively) are re-evaulated by the sound system.

Kernel function 0x31: DoSound(FADE, Object])

<syntax type="C">kfunct 0x31: DoSound(); word 0xa, Object sound_obj;</syntax>

(word) 0xa: The sound command subfunction number
(Object) sound_obj: The sound object affected

Returns: (void)

Fades the specified song. Fading takes approximately two seconds. The song status is set to 'stopped' (0) afterwards.

Kernel function 0x31: DoSound(CHECK_DRIVER)

<syntax type="C">kfunct 0x31: DoSound(); word 0xb;</syntax>

(word) 0xb: The sound command subfunction number

Returns: (word) 1 if the sound driver was installed successfully, 0 if not

Kernel function 0x31: DoSound(ALL_STOP)

<syntax type="C">kfunct 0x31: DoSound(); word 0xc;</syntax>

(word) 0xc: The sound command subfunction number

Returns: (void)

Stops all music and sound effects.

Kernel function 0x32: NewList()

<syntax type="C">kfunct 0x32: NewList();</syntax>

Returns: (DblList) The address of a new node list on the heap

This function allocates and initializes a node list containing no elements.

Kernel function 0x33: DisposeList(DblList)

<syntax type="C">kfunct 0x33: DisposeList(); NodeList list;</syntax>

(NodeList) list: The list to dispose

Returns: (void)

Frees all memory associated to a list.

Kernel function 0x34: NewNode(word, word)

<syntax type="C">kfunct 0x34: NewNode(); word value, word key;</syntax>

(word) value: The node value
(word) key: The node key (used for searching the list)

Returns: (Node) A new node

This function allocates a new node and initializes it with the key and value passed as parameters.

Kernel function 0x35: FirstNode(DblList)

<syntax type="C">kfunct 0x35: FirstNode(); DblList list;</syntax>

(DblList) list: The list to examine

Returns: (Node) The first node of the list, or 0 if the list is empty

Kernel function 0x36: LastNode(DblList)

<syntax type="C">kfunct 0x36: LastNode(); DblList list;</syntax>

(DblList) list: The list to examine

Returns: (Node) The last node of the list, or 0 if the list is empty

Kernel function 0x37: EmptyList(DblList)

<syntax type="C">kfunct 0x37: EmptyList(); DblList list;</syntax>

(DblList) list: The list to check

Returns: (int) 1 if list is an empty list, 0 if it isn'tv

Kernel function 0x38: NextNode(Node)

<syntax type="C">kfunct 0x38: NextNode(); Node node;</syntax>

(Node) node: The node whose succcessor is to be found

Returns: (Node) The node following the supplied node, or 0 if none is available.

Kernel function 0x39: PrevNode(Node)

<syntax type="C">kfunct 0x39: PrevNode(); Node node;</syntax>

(Node) node: The node whose predecessor is to be determined

Returns: (Node) The supplied node's predecessor, or 0 if the node has no predecessor

Kernel function 0x3a: NodeValue(Node)

<syntax type="C">kfunct 0x3a: NodeValue(); Node node;</syntax>

(Node) node: The node whose value is to be determined

Returns: (word) The value associated with the specified node

Kernel function 0x3b: AddAfter(DblList, Node, Node)

<syntax type="C">kfunct 0x3b: AddAfter(); DblList list, Node ref_node, Node new_node;</syntax>

(DblList) list: The list to insert into
(Node) ref_node: The node in list to insert after
(Node) new_node: The node to insert

Returns: (void)

This function inserts new_node into list as the immediate successor of ref_node.

Kernel function 0x3c: AddToFront(DblList, Node)

<syntax type="C">kfunct 0x3c: AddToFront(); DblList list, Node node;</syntax>

(DblList) list: The list the node is to be added to
(Node) node: The node to add

Returns: (void)

This function adds a node to the beginning of a doubly linked list.

Kernel function 0x3d: AddToEnd(DblList, Node)

<syntax type="C">kfunct 0x3d: AddToEnd(); DblList list, Node node;</syntax>

(DblList) list: The list to add the node to
(Node) node: The node to add to the list

Returns: (void)

This function adds the specified node to the end of the specified list.

Kernel function 0x3e: FindKey(DblList, word)

<syntax type="C">kfunct 0x3e: FindKey(); DblList list, word key;</syntax>

(DblList) list: The list in which the key is to be sought
(word) key: The key to seek

Returns: (Node) The node containing the key, or 0 if no node contains it

This function searches for a specific key in the nodes of a doubly linked list.

Kernel function 0x3f: DeleteKey(DblList, word)

<syntax type="C">kfunct 0x3f:(); DblList list, word key;</syntax>

(DblList) list: The list to examine
(word) key: The key to find

Returns: (void)

This function searches in the supplied list for the specified key and removes the node containing it, if any can be found.

Kernel function 0x40: Random(word, word)

<syntax type="C">kfunct 0x40: Random(); word min, word max;</syntax>

(word) min: The minimum result
(word) max: The maximum result

Returns: (word) A random number between min and max (inclusive)

Kernel function 0x41: Abs(word)

<syntax type="C">kfunct 0x41: Abs(); word value;</syntax>

(word) value: The value to absolutize

Returns: (word) The absolute value of the specified parameter

This function interprets the supplied value as a signed value and returns its absolute value.

Kernel function 0x42: Sqrt(word)

<syntax type="C">kfunct 0x42: Sqrt(); word value;</syntax>

(word) value: The value to draw the square root out of

Returns: (word) The square root of the supplied value

Kernel function 0x43: GetAngle(Point, Point)

<syntax type="C">kfunct 0x43: GetAngle(); Point origin, Point destination;</syntax>

(Point) origin: The point to look from
(Point) destination: The point to look to

Returns: (word) A positive angle between the two points, relative to the screen coordinate axis.

This function returns approximately the following value: -(180.0/PI * atan2(destination.y - origin.y, destination.x - origin.x)) + 180; Where atan2(double, double) is the libm function.

Kernel function 0x44: GetDistance(Point, Point)

<syntax type="C">kfunct 0x44: GetDistance(); Point foo, Point bar;</syntax>

(Point) foo: A point in two-dimensional integer space
(Point) bar: Another two-dimensional integer point

Returns: (int) The euklidian distance between the points foo and bar

Kernel function 0x45: Wait(word)

<syntax type="C">kfunct 0x45: Wait(); word ticks;</syntax>

(word) ticks: The number of game ticks (60 Hz beats) to wait

Returns: (word) The time passed in between the finish of the last Wait() syscall

Kernel function 0x46: GetTime([word])

<syntax type="C">kfunct 0x46: GetTime(); word mode;</syntax>

(word) mode: If this parameter is supplied, the time of day is returned.

Returns: (word) Either the time of day in seconds, or the elapsed number of ticks since the interpreter started.

This function is somewhat strange, because it determines its behavior not by the value of a parameter passed, but by its presence instead. Please note that the time of day in this case does not distinguish between am and pm.

Kernel function 0x47: StrEnd(HeapPtr)

<syntax type="C">kfunct 0x47: StrEnd(); HeapPtr string;</syntax>

(HeapPtr) string: The string whose terminator should be found

Returns: (HeapPtr) The address of the null terminator of the indexed string

Kernel function 0x48: StrCat(HeapPtr, HeapPtr)

<syntax type="C">kfunct 0x48: StrCat(); HeapPtr dest, HeapPtr source;</syntax>

(HeapPtr) dest: The string whose end is appended to
(HeapPtr) source: The string to append

Returns: (HeapPtr) dest

This function concatenates two strings on the heap.

Kernel function 0x49: StrCmp(HeapPtr, HeapPtr[, word])

<syntax type="C">kfunct 0x49: StrCmp(); HeapPtr foo, HeapPtr bar[, word length];</syntax>

(HeapPtr) foo: The one string to compare
(HeapPtr) bar: The other string to compare
(int) width: The maximum number of characters to compare

Returns: (word) -1 if foo is less than bar, 0 if both are equal, 1 if foo is greater than bar

This function simply encapsulates the libc strcmp(char *, char *) and strncmp(char *, char *, int) functions.

Kernel function 0x4a: StrLen(HeapPtr)

<syntax type="C">kfunct 0x4a: StrLen(); HeapPtr string;</syntax>

(HeapPtr) string: The string whose length should be calculated

Returns: (word) The length of the specified string

Kernel function 0x4b: StrCpy(HeapPtr, HeapPtr[, word])

<syntax type="C">kfunct 0x4b: StrCpy(); HeapPtr dest, HeapPtr src[, word length];</syntax>

(HeapPtr) dest: The destination to copy the string to
(HeapPtr) src: The source from which the string is to be copied
(word) length: The maximum length of the string to copy

Returns: (HeapPtr) dest

Copies a string, plus the trailing \0 terminator. The length of the string may be reduced with the optional length parameter. This function simply encapsulates the libc strcpy(char *, char *) and strncpy(char *, char *, int) functions.

Kernel function 0x4c: Format(HeapPtr, String,...)

<syntax type="C">kfunct 0x4c: Format(); HeapPtr dest, String format, parameters...;</syntax>

(HeapPtr) dest: The heap destination to write to
(String) format: The format to use
(misc) parameters: The values and strings to insert

Returns: (HeapPtr) dest

This syscall acts as a frontend to the libc sprintf(char *, char *) function.

Kernel function 0x4d: GetFarText(word, word, HeapPtr)

<syntax type="C">kfunct 0x4d: GetFarText(); word resnr, word stringnr, HeapPtr dest;</syntax>

(word) resnr: Number of the text resource to retreive the text from
(word) stringnr: Number of the string inside the resource to retreive
(HeapPtr) dest: The destination to write the text to

Returns: (HeapPtr) dest

Retrieves a string from a text resource and puts it on the heap.

Kernel function 0x4e: ReadNumber(HeapPtr)

<syntax type="C">kfunct 0x4e: ReadNumber(); HeapPtr src;</syntax>

(HeapPtr) src: The address of the string to interpret as a number

Returns: (word) The numeric value of the supplied string

This function acts as a frontend to the libc atoi(char *) function, with one exception: Numbers beginning with a '$' are interpreted as hexadecimal numbers.

Kernel function 0x4f: BaseSetter(HeapPtr)

<syntax type="C">kfunct 0x4f: BaseSetter(); HeapPtr view_obj;</syntax>

(HeapPtr) view_obj: The view object whose base is to be set

Returns: (void)

This method is used to set the bounding rectangle of a view. The bounding rectangle is specified by the set {brLeft, brRight, brTop, brBottom} of selectors, which indicate the window-relative boundary points of the object's bounding rectangle. The rectangle defined here is used for colission detection, among other things.

The algorithm employed by FreeSCI to determine these values appears to be either identical or very close to the original algorithm; it depends several of the object's selectors (x, y, z, ystep, view) the width and height of the view indicated by its (view, loop, cel) selectors, and that view's horizontal and vertical pixel offset modifyers (xmod, ymod). The algorithm works as follows:

<syntax type="pascal">brLeft := x - xmod - width / 2 brRight := brLeft + width brBottom := y - z - ymod + 1 brTop := brBottom - ystep</syntax>

Kernel function 0x50: DirLoop(HeapPtr, word)

<syntax type="C">kfunct 0x50: DirLoop(); HeapPtr object, word angle;</syntax>

(HeapPtr) object: The object whose loop selector is to be set
(word) angle: The angle which is to be used as a base to choose the loop angle

Returns: (void)

This function sets the loop selector of the specified object to a value implied by the 'angle' parameter, according to the following table:

angle loop value
angle < 45 || angle >= 314 3
angle >= 45 && angle < 135 0
angle >= 135 && angle < 225 2
angle >= 225 && angle < 314 1

Kernel function 0x51: CanBeHere(HeapPtr [, DblList])

<syntax type="C">kfunct 0x51: CanBeHere(); HeapPtr obj [, DblList clip_list];</syntax>

(HeapPtr) obj: The object to test

(DblList) cliplist: An optional list of objects to test obj against Returns: (int) 1 if obj can be where it is, 0 if not

This function first retreives obj’s signal and illegalBits selectors, plus its brRect (boundary rectangle, consisting of brTop, brBottom, brLeft and brRight). If either of the DONT_RESTORE or IGNORE_ACTOR flags is set, the function returns 1, otherwise it proceeds with verifying that.

illegalBits bitwise-AND the disjunction of all elements of   a pixel with the color value n inside the control map zone delimited by obj's.

 
If both conditions are met, 1 is returned. Otherwise, 0 is returned.

Kernel function 0x52: OnControl(word, Point | Rect)

<syntax type="C">kfunct 0x52: OnControl(); word map, Point|Rect area;</syntax>

(word) map: The map to check (bit 0: visual, bit 1: priority, bit 2: special)
(Point) or (Rect) Area: The point or rectangle that is to be scanned

Returns: (word) The resulting bitfield

This function scans the indicated point or area on the specified map, and sets the bit corresponding to each color value found correspondingly. For example, if scanning map 4 (special) would touch two areas, one with color value 1 and one with color value 10, the resulting return value would be 0x0402 (binary 0000010000000010).

See also "Pictures and movement control section.

Kernel function 0x53: InitBresen(HeapPtr [, word])

<syntax type="C">kfunct 0x53: InitBresen(); HeapPtr mover, word step_factor;</syntax>

(HeapPtr) mover: The mover object to initialize
(word) step_factor: A factor to multiply the step size with (defaults to 1)

Returns: (void)

Initializes a mover object for bresenham movement from the object's client's coordinates to the coordinates specified by its own pair of (x,y) selectors. To do this, it retreives the mover's client, and calculates the result values according to the algorithm for determining the initial values for iterative line drawing according to the Bresenham line algorithm:

(the following code is pseudocode Pascal using `::' notation for field access) <syntax type=Pascal>

       client := mover::client
       dx := mover::x - client::x
       dy := mover::y - client::y

       vxmax := client::xStep * step_factor
       vymax := client::yStep * step_factor

       numstepsx := |dx / vxmax|
       numstepsy := |dy / vymax|

       IF numstepsx > numstepsy THEN
               numsteps := numstepsx
               mover::b_xAxis := 1
               d0 := dx
               d1 := dy
               s := client::yStep
       ELSE
               numsteps := numstepsy
               mover::b_xAxis := 0
               d1 := dx
               d0 := dy
               s := client::xStep
       FI

       mover::dx := dx / numsteps
       mover::dy := dy / numsteps

       mover::b_di := - |d0|
       mover::b_i1 := 2 * (|d1| - |s * numsteps|) * |d0|
       mover::b_incr := d1 / |d1|
       mover::b_i2 := mover::b_d1 * 2

</syntax>

Kernel function 0x54: DoBresen()

<syntax type="C">kfunct 0x55: DoBresen();

Returns
(void)</syntax>

Executes the Bresenham algorithm on the values calculated by InitBresen, and counts down the number of steps. It then invokes CanBeHere() on the resulting coordinates, and sets the new coordinates if it actually Can Be There.

Kernel function 0x55: DoAvoider(HeapPtr)

<syntax type="C">kfunct 0x55: DoAvoider(); HeapPtr avoider;</syntax>

Returns: (word) New direction

This function is a no-op in later SCI games, but is implemented in some or all pre-0.000.576 interpreters.

Kernel function 0x56: SetJump(?)

Kernel function 0x57: SetDebug()

<syntax type="C">kfunct 0x57: SetDebug();</syntax>

Returns: (void)

This function forces the interpreter to enter debug mode. It is equivalent to pressing LShift-RShift-PadMinus.

Kernel function 0x58: InspectObj(?)

Kernel function 0x59: ShowSends(?)

Kernel function 0x5a: ShowObjs(?)

Kernel function 0x5b: ShowFree(?)

Kernel function 0x5c: MemoryInfo(word)

<syntax type="C">kfunct 0x5c: word mode(); word mode;</syntax>

(word) mode: 0 to 4 (see below)

Returns: (word) The amount of free memory on the heap, in bytes

This function returns the total amount of free memory on the heap if mode == 0. If mode equals 1, the total size of the largest chunk of heap memory is returned. In mode 2, the size of the largest available hunk memory block is returned, and mode 3 returns the total amount of free hunk memory, shiftet to the right by 4 bits.

Mode 4 was apparently introduced in SCI01 and reports the amount of free memory provided by DOS in paragraphs.

Kernel function 0x5d: StackUsage(?)

Kernel function 0x5e: Profiler(?)

Kernel function 0x5f: GetMenu(word, word)

Parameters
entry :word A pair of bytes. In LE notation, the higher byte is the ``menu ID, and the lower byte is the ``entry ID.
key :word Special key selecting some particular information regarding the menu entry.

Retrieves some metainformation about an (existing) menu entry. entry selects the menu and entry the information is recovered with respect to, and key specifies which particular information to recover. At the moment, the following kinds of information are known for key:

ID FreeSCI macro (MENU_ATTRIBUTE_...) Description
0x6d SAID The ``Said spec associated with the menu entry, or a null pointer. If this spec is matched, the next GetEvent() call will behave as if the appropriate menu option had been selected.
0x6e TEXT The string currently displayed for the menu item.
0x6f KEY An optional key (as reported by GetKey()) the menu option should be triggered by.
0x70 ENABLED Whether the menu option is enabled or not (in the latter case, it is grayed out and cannot be selected).
0x71 TAG A value without special semantics.

Kernel function 0x60: SetMenu(word, [word, any]*)

Parameters
entry : word A pair of bytes. In LE notation, the higher byte is the ``menu ID, and the lower byte is the ``entry ID.
key : word A special key selecting some particular information regarding the menu entry.
value : word A special key selecting some particular information regarding the menu entry.

SetMenu is a varargs function; it takes a menu bar entry ID (cf. GetMenu, section Kernel function 0x5f) followed by any even number of parameters. Each of these parameter pairs begins with a key; the second entry is a value whose type depends on the key. Semantics of key are as in GetMenu (cf. section Getmenu).

Kernel function 0x61: GetSaveFiles(String, String, HeapPtr*)

<syntax type="C">kfunct 0x61: GetSaveFiles(); String game_id, String strspace, HeapPtr *ptrs;</syntax>

(String) game_id: The game ID as a string
(String) strspace: The string which the result should be stored in
(HeapPtr *) ptrs: The array of pointers which the string pointers are to be stored in

Returns: (word) The number of savegames for the specified game_id

Returns an array of strings describing the existing save games for game_id. The strings are put into strspace one by one, and heap pointers to each of them are put into the ptrs array. The number of saved games is returned in the accumulator.

Kernel function 0x62: GetCWD(HeapPtr)

<syntax type="C">kfunct 0x62: GetCWD(); HeapPtr address;</syntax>

(HeapPtr) address: The address to write to

Returns: (HeapPtr) The supplied address

This function retrieves the current working directory (CWD) and stores its string representation at the location pointed to by the supplied parameter.

FreeSCI returns a sub-directory of the user's home directory, if applicable, instead of the cwd.

Kernel function 0x63: CheckFreeSpace(String)

<syntax type="C">kfunct 0x63: CheckFreeSpace(); String path;</syntax>

(String) path: The path to examine

Returns: (word) 1 if saving is possible, 0 otherwise

Returns TRUE if there would be enough space left on the specified path to save the current game (but doesn't actually save).

Kernel function 0x64: ValidPath(?)

Kernel function 0x65: CoordPri(?)

Kernel function 0x66: StrAt (String, word[, char])

<syntax type="C">kfunct 0x66: StrAt(); String src, word offset[, char replacement];</syntax>

(String) src: The string to read from
(word) offset: The offset inside the string
(char) replacement: An optional replacement value for the indexed character

Returns: (char) The character requested

This function retreives a single character from a string. Optionally, if replacement is set, the source character will be replaced with the specified replacement.

Kernel function 0x67: DeviceInfo(word, String[, String])

<syntax type="C">kfunct 0x67: DeviceInfo(); word sub_function, String string1[, String string2];</syntax>

(word) sub_function: A numeric value from 0 to 3, inclusive. See below
(String) string1: See below
(String) string2: See below

Returns: See below

Depending on the value of sub_function, this system call executes one of four defined actions:

  1. GET_DEVICE
  2. GET_CURRENT_DEVICE
  3. PATHS_EQUAL
  4. IS_FLOPPY

See the specific function definitions below for more information.

Kernel function 0x67: DeviceInfo(GET_DEVICE, String, String)

<syntax type="C">kfunct 0x67: DeviceInfo(); word GET_DEVICE, String input, String output;</syntax>

(word) GET_DEVICE: Constant sub-function identifier (0)
(String) input: A path whose device identifier should be extracted
(String) output: The destination of the device identifier

Returns: (HeapPtr) Points to the terminating zero character of output

GET_DEVICE returns the drive/device on which "input" resides in output (and a pointer to the terminating NULL in the accumulator).

Kernel function 0x67: DeviceInfo(GET_CURRENT_DEVICE, String output)

<syntax type="C">kfunct 0x67: DeviceInfo(); word GET_CURRENT_DEVICE, String output;</syntax>

(word) GET_CURRENT_DEVICE: Constant sub-function identifier (1)
(String) output: The destination which the CWD device identifier should be written to

Returns: (HeapPtr) Points to the terminating null character of output

GET_CURRENT_DEVICE returns the drive/device that contains the current working directory (and a pointer to the terminating NULL in the accumulator).

Kernel function 0x67: DeviceInfo(PATHS_EQUAL, String path1, String path2)

<syntax type="C">kfunct 0x67: DeviceInfo(); word PATHS_EQUAL, String path1, String path2;</syntax>

(word) PATHS_EQUAL: Constant sub-function identifier (2)
(String) path1: First path to compare
(String) path2: Second path to compare

Returns: (word) 1 if path1 and path2 point to the same physical location, 0 otherwise

PATHS_EQUAL returns TRUE if the two supplied paths point to the same place.

Kernel function 0x67: DeviceInfo(IS_FLOPPY, String path)

<syntax type="C">kfunct 0x67: DeviceInfo(); word IS_FLOPPY, String path;</syntax>

(word) IS_FLOPPY: Constant sub-function identifier (3)
(String) path:

Returns: (word) 1 if path is on a floppy disk, 0 otherwise

PATHS_EQUAL returns TRUE if the two supplied paths point to the same place.

Kernel function 0x68: GetSaveDir()

<syntax type="C">kfunct 0x68: GetSaveDir();</syntax> Returns: (String)

This function returns the heap position allocated to store the string representation of the save game directory. This heap space is allocated automatically during startup.

Kernel function 0x69: CheckSaveGame(String, word[, String])

<syntax type="C">kfunct 0x69: CheckSaveGame(); String game_id, word game_nr[, String version];</syntax>

(String) game_id: The savegame ID string
(word) game_nr: The savegame number
(String) version: An optional game version string

Returns: (word) 1 if the savegame is loadable, 0 otherwise

Returns TRUE if the specified save game is valid and loadable (i.e., not for another game/interpreter/version).

Kernel function 0x6a: ShakeScreen(word[, word])

<syntax type="C">kfunct 0x6a: ShakeScreen(); word times [, word direction];</syntax>

(word) times: Number of times to shake the screen
(word) direction: See below

Returns: (void)

If direction is not specified, it defaults to 1. It is a bitmask and defined as follows:

  • bit 0 Shake 10 pixels downwards
  • bit 1 Shake to the right
  • bit 2 Unknown, but used

Kernel function 0x6b: FlushResources(?)

Kernel function 0x6c: SinMult(?)

Kernel function 0x6d: CosMult(?)

Kernel function 0x6e: SinDiv(?)

Kernel function 0x6f: CosDiv(?)

Kernel function 0x70: Graph(?)

Kernel function 0x71: Joystick(word, word)

<syntax type="C">kfunct 0x71: Joystick(); word subfunction, word param;</syntax>

(word) subfunction: Always 0x0c
(word) param: Parameter for the subfunction, purpose unknown

Returns: (void)