KISS General Specification: CNF
4. Details of the Configuration file
The CoNFiguration file (CNF) is a text file that contains the
description of all images, colors,
actions
(
FKiSS) and
events (
FKiSS)
that make up a KiSS Artform. The CNF has an overall structure or syntax
that must be followed or the KiSS Artform might not display correctly.
Most viewers can provide feedback in the form of warnings or errors if a
CNF contains errors.
|
Note: Each line of the CNF file must contain less than 256 characters.
|
The character that starts a line in the CNF file dictates what that line
is for. The line could define a palette file, a cel file, a set, or some other element.
A KiSS Artform contains one or more sets (up to 10). Each set can
contain any number of cels. Any number of
KCF palette files
can be specified and each set can specify any one of the available
palettes.
Comments
A comment can be embedded in the CNF file, allowing you to make a note of what is
being defined at a particular point in the file. Comments are very useful, especially
in large CNF files.
A comment starts with a semicolon (';') and goes to
the end of the line. A KiSS viewer ignores everything from the semicolon
to the end of the line. There is one exception to this and that is if the
semicolon is followed by one of a few special characters that mark the
start of an
FKiSS rule.
Older KiSS viewers that do not understand FKiSS rules will properly ignore
them because they look like comments. Newer KiSS viewers can tell the
difference between a comment and an FKiSS rule.
Filenames in the CNF file
Palette and cel filenames are composed of the basename (up to 8 characters) plus a
filename extension (up to 3 characters). Filenames are case-insensitive, so the upper-
and lower-case characters are treated the same. Only the following characters are
allowed in a filename (other than the period separating the extension from the base
name).
ABCDEFGHIJKLMNOPQRSTUVWXYZ 0123456789 _ ~ - & ^ !
CNF Commands
; Comment
Comment lines are ignored by KiSS and can be used as a reminder, add commentary, etc.
|
Note: Comments may be appended to the end of any other line.
|
Example
; This line will be ignored.
%palette.kcf ; Everything after this semicolon will be ignored.
= Memory size
Syntax: =<memory>K
For KiSS v1.0 compatibility. Current KiSS viewers ignore this line and its use is discouraged.
Example:
=260K
( Play field size
Syntax: (<horizontal size>,<vertical size>
Defines the size of the play field. If omitted, "(448,320" is assumed for KISS v2.18 compatibility.
Example:
(640,400
% Palette file
Syntax: %<palette filename>
Declares a palette file. Palette files are numbered as 0, 1, 2... by order listed.
All colors in the palette file #0 are used. Color #0 in palette file #0 is
used as the background color.
|
Color #0 in subsequent palette files is unused.
|
The total number of colors must be 256 or less across all palettes in
all KCF palette files in viewers without Enhanced Palette Support.
Example:
%colors.KCF ; Palette file #0.
%cels18_20.kcf ; Palette file #1.
[ Border color
Syntax: [<border color index>
This color is the index of a palette entry in palette #0 of the first KCF.
The screen area outside of the play field is filled with this color.
Example:
[12 ; Set border color to color at index 12 in palette #0.
# Cel file
Syntax: #<object number>[.<fix>] <cel filename> [*<KCF number>] [:<set number>]
Declares a cel, describing the object of which it is a member, which KCF
it uses, on what sets it appears, and its initial fix value.
| Item | Description |
|---|
| <object number> |
Cels with the same object ID are members of the same object and will move
together as a unit. |
| <fix> |
How strongly this object is fixed in place.
- A value of 0 means the object is freely moveable.
- A value less than 100 means the object cannot be moved but the fix value will
reduce by 1 each time it is clicked.
- A value of 100 or higher is permanently fixed in place.
- This value may be 0 to 32767.
The fix value for an object is the maximum value for all member cels.
|
| <cel filename> |
Describes the filename of the cel including filename extension.
|
| <KCF number> |
Indicates which KCF that should be used to draw this cel.
Different instances of the same cel may use different KCFs.
Different cels within the same object may use different KCFs.
|
| <set number> |
The cel is drawn only in the sets (pages) specified.
Multiple sets may be listed, separated by spaces.
These values may be 0-9 (because the typical limit is 10 sets).
If omitted, this cel is drawn in all sets.
|
|
Note: The order in which cel declarations
are listed determine the order in which they are drawn on screen. Cels
listed first in the CNF are drawn on top of cels listed later in the
CNF.
|
Example:
#2 data1.cel ; Object 2 uses image data1.cel on all sets.
#2 data1_part.cel ; Object 2 also uses image data1_part.cel on all sets.
#3.5 data2.cel :2 3 4 ; Object 3 with fixed value of 5 uses image data2.cel
; on sets 2, 3, and 4.
#4.255 data3.cel ; Object 4 cannot be moved and uses image data3.cel on
; all sets.
#5 data4.cel *1 :6 ; Object 5 uses image data4.cel and KCF #1 on set 6.
$ Set information
Syntax: $<palette> [<xpos,ypos>...]
Palette to use followed by a list of positions for each object declared in the CNF file that
has been declared to be in this set.
Traditionally, there are a maximum of 10 sets and most KiSS viewers adhere to this limit.
A long description may be wrapped to the next line with the following lines
beginning with a space to indicate the line is continued.
| Item | Description |
|---|
| <palette> |
Initial palette for the set. This is the number of a palette within a
KCF. The range is based on the KCF with the greatest number of
palettes. The palette number starts at 0 and goes up to one less
than the greatest number of palettes.
For example, if the greatest number of palettes is 8, then
the range for a palette number is 0 through 7. If the greatest
number of palettes is 20, then the range is 0 through 19.
|
| <xpos,ypos> |
Position of object relative to the top-left corner of the play field.
Positions are listed by order of object ID number.
No spaces may appear between xpos, ypos, and the comma.
An aserisk ('*') means no position data is given for this object. If the object exists, a
position of 0,0 is assumed.
|
|
Note: The sets declarations can be overwritten by the KISS save function.
|
Example:
$2 192,11 * 56,176 55,21 259,62 15,24 375,63
$3 43,115 154,62 372,108 253,156 * * * 165,207
* 162,198 * 119,56 152,44 * * * ; Continued from previous line
16,355 394,362 108,355 * * * 125,261 ; Continued from previous line
$0 192,11 * 56,176 55,21 259,62 15,24 375,63