SCI Kernel Documentation/SCI Overview
Author: Jeff Stephenson
This document details the capabilities of the Script Interpreter (sci) and the interface to those capabilities through the Script programming language. Before getting into the specific functions we'll take a look at how sci operates in order to provide a background for the function explanations.
When sci starts up, one of the first things that it does is set up two memory spaces for memory management. One is the heap, and consists of an area smaller than 64K which can be addressed by 16 bit offsets. This is used for script code, variables, objects, lists, and other relatively small things which we wish to access quickly. When allocating memory from the heap, a pointer is returned, which is just the offset of the allocated memory within the heap. Things which exist in the heap are at fixed locations -- they are not affected by garbage collection.
The other memory space, hunk space, is much larger (128K or more, depending on the target machine) and is used to hold resources: views, pictures, text, background save areas, and anything else to which we do not need the access speed of 16 bit pointers. When a resource is loaded or allocated, sci returns a handle, which is a 16 bit pointer to a location in the heap which contains a 32 bit pointer to the resource. Since all resource access is through a handle, sci can do garbage collection in hunk space -- when there is not enough memory to load a resource, sci will rearrange the currently loaded resources in an attempt to create a large enough block of memory for the new resource. If the garbage collection is unable to create enough memory for the resource, sci will begin purging the least recently used resources from hunk space until there is enough room. Purging resources creates no problem, as any attempt to access a resource which is not in memory will cause it to be loaded. With garbage collection and automatic resource purging/loading, it is virtually impossible to run out of memory -- the worst condition which is likely to occur is constant disk access.
Once sci has initialized the memory management, graphics, etc., it turns control over to the Script pseudo-machine (pmachine), which loads script 0 and starts executing pseudo-code (pcode) with entry 0 in that script. From this point on, the pmachine executes the pcode produced by the sc compiler, making calls to the kernel routines in the interpreter and passing messages to objects to do things such as draw pictures, animate characters, etc.
Interfaces to the kernel are in kernel.sh. In the following descriptions, remember that any of the arguments can be an arbitrarily complex expression (including for example another kernel function call).
Many of the functions described here are never called directly, but are hidden in object methods (described in Script Classes for Adventure Games). These calls are given here for completeness and in case they are needed for writing new classes.