FKiSS Specifications

FKiSS is a set of commands consisting of events (things that can happen while a set is open) and actions (what to do when the events occur). FKiSS was defined in several versions where each version adding new features. FKiSS is intended to be backward compatible, meaning that old commands can be used alongside new ones. A few commands have been marked as obsolete while others have been enhanced or refined in a later version.

Tags - syntax added at the end of the object declaration lines - are FKiSS syntax, but they were introduced along with different FKiSS versions, and so have been included with the version they belong with.

FKiSS

These are the first commands that were added when KiSS was enhanced with "French KiSS", a simple scripting language to allow more user interactivity than just dragging cels with the mouse. Commands that weren't implemented in the earliest FKiSS viewers, but which were introduced too soon to fall under FKiSS2, are marked "FKiSS1b". The commands marked as obsolete have been left out in later viewers, because what they do can be achieved more easily by resizing the window and manually editing the configuration file.

Events (FKiSS)

alarm()

Syntax: alarm(number)
Example: alarm(1)

Triggered when a timer reaches zero. In FKiSS, the maximum number of alarms is 64 (0 to 63); in FKiSS1b this became 128, in FKiSS2 it was 512, and viewers made for higher versions allow 1000 alarms or more.

Related actions: timer(), randomtimer()

begin()

Syntax: begin()

Triggered by opening the set, after initialize() and before version(). This event fires after the cels on the first page have been mapped.

Related events: initialize(), end(), version()

catch()

Syntax: catch(celname/object)
Example: catch("celA.cel"), catch(#3)

Triggered when the user clicks on a cel/object, except if the cel/object clicked on has the maximal fix value.

Related events: catch() in FKiSS4, fixcatch(), press(), drop(), release()

col() (FKiSS1b)

Syntax: col(number between 0 and 9)
Example: col(6)

Triggered when the palette group changes to that number.

Related actions: changecol(), letpal()

drop()

Syntax: drop(celname/object)
Example: drop("celA.cel"), drop(#3)

Triggered when the user loses control of the object dragged, either because the mouse button is released (unfixed cel/object) or because the cel/object is fixed and snaps back into place. Doesn't work on cels or objects with a maximum fix value, since these are completely undraggable.

Related events: drop() in FKiSS4, fixdrop(), release(), catch(), press()

end()

Syntax: end()

Triggered by closing the set. Using map() under this event is usually pointless, as the viewer may close too quickly to show the result of the mapping action.

Related events: begin()
Related actions: quit()

fixcatch()

Syntax: fixcatch(cel/object)
Example: fixcatch("celA.cel"), fixcatch(#8)

Triggered when the user clicks on a fixed object/cel which doesn't have a maximum fix value.

Related events: fixcatch() in FKiSS4, catch(), press(), fixdrop(), release()

fixdrop()

Syntax: fixdrop(cel/object)
Example: fixdrop("celA.cel"), fixdrop(#8)

Triggered when the user releases a fixed object/cel which doesn't have a maximum fix value.

Related events: fixdrop() in FKiSS4, drop(), release(), fixcatch(), press()

initialize()

Syntax: initialize()

The first event triggered when the set is opened. Actions under initialize() are carried out before any cels are mapped.

Related events: begin(), version()

never() (FKiSS1b)

Syntax: never()

This event is never triggered. It can be used for debugging, or as a dummy wrapper for events that a viewer may not recognize.

Related actions: nop()

press()

Syntax: press(celname/object)
Example: press("celA.cel"), press(#8)

Triggers when the user clicks on an object/cel, no matter what its fix value is.

Related events: press() under FKiSS4, release(), catch(), fixcatch(), letcatch()

release()

Syntax: release(celname/object)
Example: release("celA.cel"), release(#8)

Triggers when the user releases the mouse button on an object/cel previously clicked on, no matter what its fix value is. For cels/objects that don't have the maximum fix value, drop() may be a better alternative, as some viewers don't trigger release() under certain circumstances.

Related events: release() under FKiSS4, press(), drop(), fixdrop()

set()

Syntax: set(number between 0 and 9)
Example: set(4)

Triggers when the page with that number is made the active page.

Related actions: changeset(), letset()

unfix()

Syntax: unfix(celname/object)
Example: unfix("celA.cel"), unfix(#11)

Triggered when the lock value of the object/cel turns to zero, and it becomes draggable. The argument is usually an object number, as it is the lock value of the whole object which determines when any cel in that object becomes draggable.

Related actions: unfix() under FKiSS4, setfix(), letfix()

Actions (FKiSS)

altmap()

Syntax: altmap(celname/object)
Example: altmap("celB.cel"), altmap(#6)

Maps the cel, or all cels of the object, that were unmapped, on every page; unmaps those that were mapped.

Related actions: altmap() under FKiSS4, map(), unmap(), ifmapped(), ifnotmapped()

changecol()

Syntax: changecol(number between 0 and 9)
Example: changecol(0)

Sets the palette group of the current page to the number value, so that all cels with an external palette are displayed using the internal palette of that palette group number.

Related events: col()
Related actions: letpal()

changeset()

Syntax: changeset(number between 0 and 9)
Example: changeset(3)

Closes the previous page and opens the page with that number.

Related events: set()
Related actions: letset()

debug()

Syntax: debug(string in quotes)
Example: debug("This is an error message")

Outputs the text in the string to a dialog or text file, depending on the viewer.

Related actions: notify()

map()

Syntax: map(celname/object)
Example: map("celB.cel"), map(#6)

Maps the cel, or all cels in the object, on every page.

Related actions: map() under FKiSS4, unmap(), altmap(), ifmapped(), ifnotmapped()

move()

Syntax: move(object,pixels to right,pixels down)
Example: move(#25,100,-60)

Moves the object the given number of pixels away from its current X/Y coordinates, on the current page. Negative values move the object up and to the left.

Related actions: movebyx(), movebyy(), moveto(), moverandx(), moverandy(), movetorand(), ifmoved()

nop()

Syntax: nop()

"No action performed"; does nothing. Useful for debugging, or in an if-else-end block.

Related events: never()

quit() (FKiSS1b)

Syntax: quit()

Closes either the set or the viewer, depending on the viewer.

Related events: end()

randomtimer()

Syntax: randomtimer(alarm,duration,range)
Example: randomtimer(11,5000,6000)

Sets a timer to a randomly chosen time between "duration" and "duration + range". In the example, the alarm would go off after at least 5 and at most 11 seconds.

Related events: alarm()
Related actions: timer()

shell() (Non-standard)

Syntax: shell(string with command)
Example: shell("echo Hi there")

Shells to the operating system and runs the string as a command. This is a very dangerous action – something like "shell("FORMAT C:")" would be carried out without warning the user – and is consequently not implemented in most viewers.

Related actions: debug(), notify()

sound()

Syntax: sound(music file)
Example: sound("creak.wav")

Plays a soundfile in either wav or au format.

Related actions: music()

timer()

Syntax: timer(alarm,duration)
Example: timer(63,2500)

Sets an alarm to go off as soon as the timer has counted down from its initial value to zero. The duration is given in milliseconds, so that "2500" equals 2.5 seconds. In FKiSS and FKiSS2, the maximum duration is 32767 (approximately 30 seconds); in higher versions, a timer may be any length. Setting the duration to 0 turns off the timer, so that the alarm doesn't fire.

Related events: alarm()
Related actions: randomtimer(), iffixed(), ifnotfixed(), ifmapped(), ifnotmapped(), ifmoved(), ifnotmoved()

transparent() (FKiSS1b)

Syntax: transparent(celname/object, number)
Examples: transparent("celB.cel",50), transparent(#30,-10)

Alters the transparency of the cel or all cels in the object by adding the number value to it, to a maximum of 255 and a minimum of 0. Positive values make the cel/object more transparent, negative values more opaque.

Related actions: let transparent() in FKiSS4, lettransparent()
Related tags: %t

unmap()

Syntax: unmap(celname/object)
Example: unmap("celB.cel"), unmap(#6)

Unmaps the cel, or all cels in the object, on every page.

Related actions: unmap() under FKiSS4, map(), altmap(), ifmapped(), ifnotmapped()

viewport()

Syntax: viewport(X coordinate, Y coordinate)
Example: viewport(100,150), viewport(50,-80)

This moves the coordinates of the viewport (the section of the playfield visible in the viewer window) by a relative amount in pixels. The viewport can't be moved beyond the playfield boundaries. This command only has effect if the viewer window is made smaller than the playfield, which sets both viewport coordinates to (old windowsize - new windowsize) / 2. Expanding the viewer window to its maximum size sets the coordinates to 0,0.

viewport(50,-80) moves the viewport 50 pixels to the right and 80 up.

Related actions: windowsize()

windowsize()

Syntax: windowsize(width,height)
Example: windowsize(500,400), windowsize(-100,200)

This changes the size of the viewer window (but not the playfield) by a relative amount in pixels, where the maximum size is the size of the playfield and the minimum size is 0,0 (which may make the viewer window disappear). When the window is made smaller, the viewport is automatically centered over the playfield.

windowsize(-100,200) makes the window 100 pixels narrower and 200 pixels higher.

Related actions: viewport()