This document is meant to be a reference for users and implementers of Kitterspeak, a scripting language for animating graphical shapes used by the MMOSG Furcadia.
Each Furcadia shape has four layers, at which it may draw its frames. These are, in order from bottom to top:
BG- background,BEHIND- behind furre,- furre (not directly usable),
FRONT- in front of furre,FG- foreground.
If a furre is present in the shape (in case of items, for example), then the two former layers are drawn behind the furre and the two latter ones are drawn in front of them. Otherwise, these frames are drawn from bottom to top.
When no kitterspeak is present in a shape, then the default is to draw the first frame of that object on the default layer BEHIND, except for Effect shapes, where the default layer becomes FRONT.
Kitterspeak execution loops by default. After executing the last line, the execution goes back to the first line.
There are two kinds of delays in Kitterspeak: automatic frame delay and manual frame delay.
Automatic frame delay is triggered every time a frame is shown, except for the situations where the next KS rule is a delay (rule no. 2) or a random delay (rule no. 15) - then the manual delay is executed instead.
Let's consider a small conceptual example:
1: show frame A
2: show frame B
3: show frame C
4: delay 1000ms
After 1: the automatic delay is triggered. After 2:, the automatic delay is also triggered. After 3: the automatic delay is not triggered and the manual delay from 4: is immediately triggered instead.
It is good to think of manual delay as an exception to the automatic delay. For shapes that have multiple delays of the same length and only few delays of differing lengths, it is convenient to set an automatic delay to the common value and instead write delay rules in the places where a different delay length is desired.
Each Kitterspeak line is composed of up to three numeric values: the step ID that denotes the type of a given Kitterspeak line, and up to two arguments accepted by that particular step ID.
In FOX5 files, each Kitterspeak line is defined as a triplet:
- UInt16
StepId, - Int16
Arg1, - Int16
Arg2.
The first argument, StepId, denotes the type of the Kitterspeak rule, as on the below list.
The latter two arguments, Arg1 and Arg2, may or may not be used, depending if the rule denoted by StepID accepts zero, one or two arguments. If unused, the arguments should be 0.
FOXed ignores KS lines with StepId equal to 0 or greater than 33.
The following lists all legal Kitterspeak rule types. The number in brackets is the internal number of the KS line. The two arguments that a step may take are denoted via M and N - if they are present inside a step description, then the step takes them as arguments.
The below rule types are grouped thematically. Please see the attached file for a screenshot of all rules in numerical order.
While the below list attempts to be comprehensive and describe all legal Kitterspeak rule types, note that not all of these rules may be available for selection in FOXed - they may be supported for legacy files only or deprecated algogether.
Implementations should be able to optimize Kitterspeak scripts which are loop-invariant, meaning that executing the same script over and over will not have any effect on the resulting shape. A simple example of such a script is:
1: show frame A behind the furre
2: show frame B in front of the furre
3: show frame C in the foreground
In this case, this script is meant to create a composite shape out of multiple frames without any animation. This Kitterspeak may be safely executed once and then stopped.
Draws frame M on the BG layer. If frame M is currently visible on another layer, it is removed from that layer. The automatic frame delay is triggered immediately afterwards.
Draws frame M on the BEHIND layer. If frame M is currently visible on another layer, it is removed from that layer. The automatic frame delay is triggered immediately afterwards.
Draws frame M on the FRONT layer. If frame M is currently visible on another layer, it is removed from that layer. The automatic frame delay is triggered immediately afterwards.
Draws frame M on the FG layer. If frame M is currently visible on another layer, it is removed from that layer. The automatic frame delay is triggered immediately afterwards.
If frame M is currently being displayed on a layer, it is moved backward one space (FG -> FRONT -> BEHIND -> BG), using the following conditions:
- M is already at the back (
BG): Nothing happens. - Free space directly behind M: M is moved into that free space.
- Free space somewhere behind M: Layers are moved backward one space as necessary to fill that free space, and M is moved backward.
- No free spaces behind M: M swaps places with the layer directly behind it.
If frame M is currently being displayed on a layer, it is moved forward one space (BG -> BEHIND -> FRONT -> FG), using the following conditions:
- M is already at the front (
FG): Nothing happens. - Free space directly in front of M: M is moved into that free space.
- Free space somewhere in front of M: Layers are moved forward one space as necessary to fill that free space, and M is moved forward.
- No free spaces in front of M: M swaps places with the layer directly in front of it.
Implementations should be able to ignore Kitterspeak scripts that consist solely of flow control instructions. This is to avoid running flow-controlling code in tight loops.
Pauses KitterSpeak execution for the next M milliseconds.
Pauses KitterSpeak execution for a random amount of milliseconds between M and N.
Sets the automatic frame delay that will be used by the various 'show frame' rules. It defaults to 0.
Sets the automatic frame delay to a range of values, similar to rule 11. A different random delay is chosen between M and N milliseconds each time the delay activates.
Increments the rule's internal loop counter L. If L <= N, then jump to step M. Otherwise, set L to 0 and continue.
Jumps to step M.
Hammer time. Halts further Kitterspeak execution.
Unofficial proposal: implementations which are meant to showcase Kitterspeak objects may allow this rule to introduce a long delay instead of halting Kitterspeak execution completely.
Set the frame's X offset from the (0, 0) point to M pixels. M may be positive or negative. Overrides the frame-provided position for all layers.
Set the frame's Y offset from the (0, 0) point to M pixels. M may be positive or negative. Overrides the frame-provided position for all layers.
Set the furre's X offset from the (0, 0) point to M pixels. M may be positive or negative.
Unofficial proposal: implementations which do not concern themselves with drawing furres in objects are not required to implement this rule.
Set the furre's Y offset from the (0, 0) point to M pixels. M may be positive or negative.
Unofficial proposal: implementations which do not concern themselves with drawing furres in objects are not required to implement this rule.
Sets the overall opacity value for this object to M (0 = transparent, 255 = opaque).
When a slide is in progress and then a second slide or a set on the same value is executed, the first slide stops immediately and the second slide begins. The starting position for the second slide is equal to the current position the object had at the moment of stopping.
Multiple consecutive slides can be run as long as no two of them affect the same value.
Like rule 5, but the value is linearly adjusted to M over the next N milliseconds. The starting value for the slide is either the default layer's X position (if no override has been performed using rule 5 or 18), or the current overridden X position.
Like rule 6, but the value is linearly adjusted to M over the next N milliseconds. The starting value for the slide is either the default layer's Y position (if no override has been performed using rule 6 or 19), or the current overridden Y position.
Like rule 7, but the value is linearly adjusted to M over the next N milliseconds. The starting value for the slide is either the default layer's furre X position (if no override has been performed using rule 7 or 20), or the current overridden furre X position.
Unofficial proposal: implementations which do not concern themselves with drawing furres in objects are not required to implement this rule.
Like rule 8, but the value is linearly adjusted to M over the next N milliseconds. The starting value for the slide is either the default layer's furre Y position (if no override has been performed using rule 8 or 21), or the current overridden furre Y position.
Unofficial proposal: implementations which do not concern themselves with drawing furres in objects are not required to implement this rule.
Like rule 17, but the value is linearly adjusted to M over the next N milliseconds.
Controls how the camera is offset when a furre is standing on this object. If M is 1, the camera will be offset along with the furre. If M is 0, the furre will be offset and the object will remain in the centre of the screen. Defaults to 0.
Unofficial proposal: implementations which do not concern themselves with drawing furres on objects are not required to implement this rule.
This rule only affects Effect shapes, and controls the order in which the 'back' sprites (BG and BEHIND layers) and the 'front' sprites (FRONT and FG layers) for particular objects are rendered in-game.
- 0 - Legacy: Item Back -> Effect Back -> Furre -> Item Front -> Effect Front
- 1 - Wrap Item and Furre: Effect Back -> Item Back -> Furre -> Item Front -> Effect Front
- 2 - Wrap Furre: Item Back -> Effect Back -> Furre -> Effect Front -> Item Front
Shapes that contain at least one of rules 23, 24, 29, 30 (the layer-based Show Frame rules) or 33 will default to Wrap Item and Furre. Other shapes will default to Legacy. The Legacy mode cannot be activated through rule 33; it only exists as a default to support objects with old KitterSpeak code.
Unofficial proposal: implementations which do not concern themselves with drawing effects on other shapes are not required to implement this rule.
These rules are not meant to be used in newly created Kitterspeak and are only here for supporting legacy files.
Implementations are encouraged to not display these rules for user selection.
Implementations may automatically convert all encountered legacy Kitterspeak to its modern counterparts.
Draws frame M on the active legacy layer. This layer defaults to BEHIND (or FRONT for Effect shapes), but rules 9 and 10 can change it. The automatic frame delay is triggered immediately afterwards.
Legacy. New shapes should use rules 23, 24, 29 or 30 which explicitly specify a layer.
If the active legacy layer is currently set to BEHIND, the frame currently visible on the BEHIND layer is moved to the FRONT layer and the active legacy layer is set to FRONT. If the active legacy layer is not currently set to BEHIND, nothing happens.
Legacy. Used in conjunction with rule 1.
If the active legacy layer is currently set to FRONT, the frame currently visible on the FRONT layer is moved to the BEHIND layer and the active legacy layer is set to BEHIND. If the active legacy layer is not currently set to FRONT, nothing happens.
Legacy. Used in conjunction with rule 1.
DEPRECATED. Never implemented in an official client for complexity reasons.
DEPRECATED. Never implemented in an official client for complexity reasons.
DEPRECATED. Never implemented in an official client for complexity reasons.
DEPRECATED. Not available in FOXEd.
DEPRECATED. Not available in FOXEd.
This document © its authors. Licensed under the CC0 license.
Furcadia © Dragon's Eye Productions, Inc. All rights reserved.
