This howto expands a bit on tea's colour-cycling tutorial. Her method can be used to cycle colour, shape (like raising and lowering a hood) or whatever you can think of, but I'm going to concentrate on the colour-changing function, and instead of a head with three hairstyles, I'm going to use a flower with six colours of petals. There are two basic cels, a stalk cel and a flowerhead cel; the flowerhead cel can be copied and filled in with different colours to make differently coloured petals.

refinement 1: using layer order

In tea's tutorial, only one of the cycling cels is mapped at a time. But for cels that exactly cover each other, only the topmost mapped cel will be visible anyway, so you can have them all mapped and "click away" each cel until you get to the bottom cel, and clicking that one remaps all the cels.

The object and cel declarations will look like this:

And the code looks like this:

(etc. - repeat for all but last cel)

Note that object #1 includes all parts of the flower, so you can freely drag it around.

refinement 2: putting all cycling cels into one object

This makes for easy coding when you can't use layer order, and know that the object won't be moved around. The object declarations are:

And the code goes:

and so on, up to and including the purple petals.

Note that flowerheads and stalk are now two different objects. This flower has to be locked into place, or it and its petals will part company.

refinement 3: using the same cel with different palettes

This solution requires a basic knowledge of palettes. It uses the same cel six times with six different object numbers, which keeps down the size of the set but uses up much RAM, possibly making the set slow to load and play with. In the basic flower palette, colour number 5, which colours the petals, is red. Cels themselves are colourless, so if I make five more palettes in which colour 5 is respectively pink, orange, blue, yellow or purple, list these in the cnf header and define the objects as follows:

then I can colour-cycle by alternating objects, like this:

and so on, up to:

Note that this flower, like the one before, has to be locked in place or its petals will go flying off in all directions.

refinement 4: using merged palettes

This solution assumes a more in-depth knowledge of palettes. It is possible to pack up to ten palettes into a palette file. Each of these ten can be made visible by activating its "palette group", but this will also activate that palette group for any other palette used. Anyway, suppose you have one merged palette. This is how you define the flower object:

This is a flower that can be dragged around without losing parts. The colour will change when the palette group does. This can't be done by clicking on the petals (unless you use FKiSS3, where you can have a variable to keep track of the palette group number) so it needs something like a button object to click:

and so on until the last button cel:

Which means that the cels of the button object are being cycled, using the first method described above.

Or you can simply use the viewer's own palette buttons, in which case no FKiSS is required whatsoever. This method requires only one cel, one object and one palette, making it a big space-saver if you don't need more than ten different colours.

refinement 5: using transparent()

In this example, cels are not unmapped, but made transparent, allowing the cel beneath to shine through. This solution is clunky rather than refined, but it may allow for extra steps in the colour cycling if you make a cel semi-transparent, which blends its colour with the cel underneath, rather than making it fully see-through straight away. The object declarations may, but don't have to, look like that of the first method, with a transparency tag added:

As you can see, this is again a flower that won't separate into components when moved around, although you could also make each ring of petals a different object, since transparent() works both with cels and objects. Since the cels are never unmapped, you can't cycle through them by clicking on them (unless you use FKiSS3 to count the number of clicks), so you have to add an extra button object as in the previous example. The code might look like:

and so on. Or, you might try intermediate transparencies:

This tip was originally submitted to the KiSS mailing list by the Invisible Phan.

Blinking is easily the most frequently used FKiSS effect, but when the doll can have different eyeshadow colours, you have to keep track of what the eyelid colour is, so that you don't map the purple-lidded half-closed eye over the green-lidded open eye, or the flesh-colour closed eyelid over the blue-shaded half-open one. This can be kept track of in FKiSS3 with variables, or you can use a different set of blinking alarms for each eyelid colour, stopping one set and starting another when the colour changes, but there is a much simpler method: transparent eyelids.

The most basic blinking-doll construction is a cel of a base doll with open eyes drawn on the face, and a cel of closed eyelids which are periodically mapped to cover the eyes. This method requires that the open eyes become a separate cel. You now have: a doll with no eyes, just two holes filled with the flesh tone of the base doll (and possibly outlined, to make it easier to fill in the eyelid colour cels later) a pair of eyes that completely covers these holes, and a pair of closed eyelids that also completely covers these holes. You may want to add a pair of half-closed eyes for smoother animation. Now, the eyelid cels must be flooded with the transparent background colour. You can keep the lashes and any outlines, but the "flesh" part should be the background colour. The rim of eyelid visible on each open eye should also be filled with the background colour. (As should the eyelid part of the half-closed eyes cel, if there is one.) The blink cycle, rather than just mapping the eyelid cels over the eyes now and then, should now map the eyelid cels and unmap the eye cels, so that the eyelid cels lie directly on top of the eyeless face. What colour are the eyelids going to be? That's right, the same colour as the face.

Now I want to add blue eyeshadow. Rather than making extra closed-eyelid and half-open-eye cels with the eyelids coloured blue, I make two patches of blue that exactly cover the eye holes. (This is where it's handy to have the eye holes outlined on the face: I can copy the base doll image, flood-fill the eye holes with the eyeshadow colour, then erase the rest of the copy.) In the cnf, these two patches of colour go over the face, but under the eyes and eyelids. When I want the doll to have blue eyeshadow, I map those colour patches, and the blue can be seen through the transparent rim of eyelid over the open eye. When the doll blinks, the area of eyelid increases, showing more blue. (Hence the unmapping of the open eyes; else you'd still see them staring through the eyelids.) Next, I want green eyeshadow, so I copy the image file of the blue patches and flood-fill them green. When I want the eyelid colour to change, I unmap the blue patches and map the green ones. Now the eyelids appear to be green, although it's still the same open-eyes cel alternating with the same closed-lids cel when the doll blinks. I can add as many differently coloured patches as I like and cycle through them with any colour cycling method described under the colour- cycling howtos.

This howto quotes a code example from Chad Randall's KiSS .cnf layout, FKiSS/FKiSS2 command reference, and various PlayFKiSS notes, which can be found at the Big KiSS Page.

FKiSS syntax was implemented not simultaneously but sequentially, meaning, some commands were defined and viewers were programmed to understand them, then some more commands were defined and newer viewers were programmed to understand those too, and so on. This means that a viewer which is FKiSS-capable may still fail to understand the FKiSS code in a set, with two possible results: the viewer either ignores the unknown code, or starts to malfunction. Code that causes the viewer to malfunction (eg. freeze, ignore code that it should understand, or any other strange behaviour) is said to "break" the viewer. To warn the user that the viewer may not understand the FKiSS syntax in a set, FKiSS2 introduced the event version(), used with the number of a FKiSS level.

The currently existing FKiSS syntax has five levels: FKiSS, FKiSS2, FKiSS2.1, FKiSS3 and FKiSS4. The version() event works like this: put the level number of the highest FKiSS level used by the cnf in the brackets (for FKiSS3, that would be version(4) and if the viewer understands that level, it will carry out the actions under the event. As version() is an event and is triggered only once (to be exact, as soon as the parser encounters it in the cnf) it can't be used for "If viewer understands command X then do command X else do command Y" constructions; its main use is to warn the user when the set is opened in the viewer, and so it should be put above any other FKiSS code. Typically, it unmaps a warning cel that would stay mapped if the FKiSS level number was too high for the viewer. As version() is a FKiSS2 event, a FKiSS-only viewer won't even recognize it, which has the same effect as putting in a level number that is too high. The example in Chad's FKiSS2 document goes like this:

The event never() acts like a wrapper to the version() event, making the viewer believe that the unknown event is an action that belongs to never() and is consequently never executed. Another wrapper to hide events that might not be understood by the viewer is the so-called "dummy alarm"; alarm(n) is used instead of never(), where timer(n) is never set. Whichever is used, version() and its wrapper must be put above both initialize() and begin(), or the viewer may ignore both events and see the unmapping action immediately under them as belonging to initialize() or begin(), and happily unmap the warning cel even though the viewer is not FKiSS2-capable.

Depending on the viewer, version() can be used once for each level number, or simply only once. Being able to use it only once can be annoying in a set which has more warning cels: for instance, one to say that the set absolutely requires FKiSS2 and another one to say that the set will run with FKiSS2 but would look even better with FKiSS2.1. The solution is to do what never() does, with another event: only trigger the unmapping action if the viewer is up to the event. In this case, the warning "This set requires FKiSS2" can be unmapped with version(2), while the cel "But to show all the effects, you need FKiSS2.1" could be unmapped via a specifically FKiSS2.1 action that also goes under version(): ifmapped(), which sets a timer if a cel is mapped. The code would then be:

A viewer which isn't FKiSS2.1-capable will ignore ifmapped(), which means that the timer isn't set, and the second warning cel isn't unmapped.

And of course if you don't want the warning cel to stop the user from playing with the set, you can add:

I should first explain what collision detection is. There are six collision events: in(), out(), stillin(), stillout(), collide() and apart(). The first four require two object numbers in the brackets. in(#1, #2) would be triggered if objects #1 and #2 overlap now, but didn't overlap before; out(#1, #2), if the objects overlapped before, but have now moved apart; stillin(#1, #2), if the objects overlapped before and are still overlapping now, and stillout(#1, #2), if the objects didn't touch before and are still apart. collide() and apart() are like in() and out(), but use cel names instead of object numbers.

I repeatedly used the words "now" and "before"; what I mean is, after and before collision detection. When something happens to an object that triggers collision detection in a viewer, this viewer checks if this object number occurs in any collision events, and then, whether it has just collided with or moved apart from the other objects in those collision events, or was already overlapping or apart, and then fires the appropriate collision events. Collision detection is always triggered by moving the object, whether by FKiSS code or by dragging it with the mouse. Depending on the viewer, collision detection may also be triggered by (un)mapping the object, or by the automatic shift in position of the object when changing to another page, either through changeset() or by clicking on a different page number, but in most viewers this is not the case. And that can be a nuisance.

As an example: I have a vase object, which is in a different spot on each page, and a bunch-of-flowers object which has two cels, one simply the bunch of flowers, the other the same bunch of flowers wrapped up in paper. By alternately mapping these two cels, I can "wrap" and "unwrap" the bunch of flowers. When the flowers touch the vase, I want them to pop into the vase and lose their wrap, and when I pull them away from the vase, I want them to become wrapped again. The code might look like:

If I stay on page 0, this will work; the flowers pop into the vase and lose their wrap as soon as flowers and vase overlap. But now I change to page 2, where the flowers and the vase are not overlapping at all; moving actions are restricted to the page being viewed, so the flowers were only put in the vase on page 0, but mapping actions happen on all pages, so the unwrapping happens on both page 0 and 2. The viewer doesn't detect that when I go to page 2, the flowers and vase are separate, and out(#1, #2) is not triggered.

But I do want it triggered, else the flower-vase trick doesn't seem to work, so I put in a page change event for each page, from 0 to 9:

This howto is based on a post to the KiSS ML by Dov Sherman about using collide() for "localized" snap-to, and one from Alexandra Werres on how to turn snap-to on and off.

"Snap-to" is when a cel, usually a clothing cel, jumps into position over another cel, usually the base doll, often after a collision event is triggered; the general use for snap-to is having clothes position themselves correctly over the doll when they touch it, and it has a few advantages:

• It's easier on the wrist if you don't have to drag cels exactly into position.
• You don't have to worry about clothes under other clothes showing a rim of colour because they've been positioned just one pixel off.
• Sometimes it's not immediately obvious where a certain bit of clothing is supposed to be put on the doll.

But first, how to add snap-to code:

In PlayFKiSS 0.8x, this is very easy. Right-click on the "parent" object (usually the base doll) and select "Set Snap-to Parent". If this option is not in the menu, the viewer isn't in editor mode: go to Tools|Options, click on the second tab, and select "Editor mode", then try again. PlayFKiSS now remembers that the coordinates of this object are the starting point for the snap-to code. Now position a cel over the parent object, right-click on it and select "Add snap-to code". Then, save the cnf.

If you open the cnf in a text editor, you will see the added lines:

The snap-to code uses object numbers, not cel names, because only objects can have coordinates. I happen to know that object #1 is the base doll and object #5 is a hat. The movebyx(), movebyy() code tells the top left corner of the hat object to move 9 pixels down and 22 pixels to the right from the top left corner of the base doll object. If the numbers had been negative, the hat would have moved up and to the left. The in() code says that this movement should happen when the hat object and the base doll object touch. (To be exact, when the bounding boxes of the two objects touch.) This is not necessarily when the artist wants snap-to to happen, but let's first see how to add snap-to code if you don't have PlayFKiSS. To do this, drag the parent object and all the objects that should snap to it in exactly the right position, then save the cnf and open it in a text editor. The line of coordinates for the page the objects have been arranged on might look like this:

Objects are counted starting at 0, so I can see that objects 0 to 6 have the following coordinates:

object #0: 0,0
object #1: 0,0
object #2: 59,56
object #3: 138,156
object #4: 133,6
object #5: 9,22
object #6: 125,120

The coordinates tell me how many pixels the top left corner of each object is away from the top left corner of the screen. I can see at a glance that object #5 is 9 pixels down and 22 pixels to the right of object #1. If I wanted it to snap to object #2, I would have to do the following sum:

59 - 9 = 50, code = movebyx(#2, #5, 50)
56 - 22 = 34, code = movebyy(#2, #5, 34)

Now, to decide what event will cause the snap-to. It could be:

- the hat touching the base doll.
- the hat touching an object other than the base doll.
- a "button" cel being clicked (ie. a press() event).
- an alarm going off.
And so on.

If I wanted simple snap-to, I could keep the in() event: if the hat touches the doll, it whizzes to the doll's head. But I may want to be able to put the hat in the doll's hands too, so it should only jump on the doll's head if it touches the doll's face. It is then more convenient to take a different object, which may simply be a circle in one colour, and put that in the same position as the doll's face, but one layer below it, so it is hidden by the doll but can still trigger a collision event when the hat object touches it. If this new object, which is strictly for the localized snap-to, is object #7, then the code becomes:

Note that the order of the object numbers doesn't matter for the in() object, but it does matter for the "moveby" actions, as the first object number "snaps to" the second.

Now that the snap-to is brought about by a cel which is hidden, the snap-to effect can easily be turned off by unmapping that cel, and turned on by remapping it. This can also be done in many ways, but a simple way is with a button cel:

An alternative way, if the snap-to is caused by the hat touching the base doll itself, is to assign the base doll cel to two different object numbers: