SCI/Specifications/SCI in action/Notes on the kernel calls

Notes on the kernel calls

Two versions of this API were used, the early GetMessage() which had only one function, and a later subfunction-based one. While GetMessage() required one to specify noun/module/verb on every call, the later Message() was able to remember this for you (by way of GET and NEXT subfunctions) - hence the appeal of recursion. Unless otherwise noted, a missing message causes the functions to copy a dummy message to the output buffer. The sequence number is incremented after fetching the message, but not tested for validity until a subsequent call to NEXT.

GetMessage syscall

(GetMessage noun module verb buffer)

Copies the message given by the tuple {module, noun, verb) to the output buffer. Returns: The buffer address

Message syscall

Subfunctions of the Message syscall:

(Message GET module noun verb cond seq buffer)

If buffer is non-NULL, copies the message given by the message tuple to the output buffer. Resets any resource-internal recursion (but not the script-controlled ditto).

If buffer is NULL, nothing is copied (obviously). :Although recursion is followed for purposes of returning a talker value, the stack is left pointing at the tuple given in the parameters - the sequence number is not incremented either. Also affects the LASTMESSAGE subfunction, q.v.

Returns: On success, the talker value associated with the message is returned in both cases. On failure, 0 is returned.

(Message NEXT buffer)

Same as above, except that the message returned is the one following the previously returned one, where “following” means having the immediately following sequence number. If no such message is found, NEXT continues at the message given by the last stack frame (script-controlled recursion being ignored). If the stack is empty, a dummy message is returned.

(Message SIZE module noun verb cond seq)

Returns the size (in bytes) of the message given by the message tuple, including the terminating zero. :Does not touch the GET/NEXT stack, although recursion is otherwise handled normally.

(Message REFCOND module noun verb cond seq)

If the indicated message recurses, returns the condition it recurses to, —1 otherwise.

(Message REFVERB module noun verb cond seq)

If the indicated message recurses, returns the verb it recurses to, —1 otherwise.

(Message REFNOUN module noun verb cond seq)

If the indicated message recurses, returns the noun it recurses to, —1 otherwise.

(Message PUSH)

Saves the current resource-internal recursion context on a stack.

(Message POP)

Restores the last resource-internal recursion context.

(Message LASTMESSAGE *tuple)

*tuple is a pointer to an array. The message tuple of the last proper message is stored in this array. By “proper” I mean that recursion pointers are followed and instances where buffer was NULL are ignored.

SCI and FreeSCI signal bits

Bit #	Name	FreeSCI constant K VIEW SIG FLAG ...	Meaning
0		STOP UPDATE	A view updating process has ended
1		UPDATED	The view object is being updated
2	noUpd	NO UPDATE	Don’t actually draw the view
3		HIDDEN	The view is hidden from sight. Often, if an actor is supposed to enter and exit a room (such as the guards in the plazas in QfG2), this bit is used. When he’s supposed to enter the room, bit 3 in his signal is cleared. When he leaves, bit 3 is set, but his SCI object is not deleted.
4	fixPriOn	FIX PRI ON	If this bit is set, the priority of the view never changes (if it isn’t, the interpreter recalculates the priority automagically).
5		ALWAYS UPDATE
6		FORCE UPDATE
7		REMOVE	The view should be removed from the screen (an interpreter bit - its corresponding script bit is bit 3). If bit 3 isn’t set as well, the view reappears on the next frame.
8		FROZEN	Deactivates the mover object of the view (it is ”frozen” - the view can still turn, however).
9	isExtra	IS EXTRA
10		HIT OBSTACLE	The view hit an obstacle on the last animation cycle.
11		DOESNT TURN	Meaningful for actors only. Means that the ac­tor does not turn, even though he is walking the ”wrong way”.
12		NO CYCLER	The view cycler is disabled. This makes the view float instead of walk.
13	ignoreHorizon	IGNORE HORIZON
14	ignrAct	IGNORE ACTOR	Actors can walk in the rectangle occupied by the view. The behavior of this bit is odd, and best ex­pressed by example. The Guild Master in QfG1 has his bit 14 set. This means that ego (or someone else) can walk all the way to his chair (try sneaking in on him from behind). If we clear this bit, we can’t sneak in on him.
15		DISPOSE ME	The view should be disposed
		FREESCI PRIVATE	Used as an intermediate result by the inter­preter; marks views that are going to have their nsRect/lsRect regions redrawn (for the test in the main draw algorithm’s step 17.1., below).
		FRESCI-STOPUPD	View has been ’stopupdated’. This flag is set when­ever the view has the STOP UPDATE bit set, and cleared as soon as it moves again. Stopupdated views are collided against differently than normal views.