KISS/GS ( KISS General Specification ) Manual by K.O.S. <<<<<<<< KISS/GS (v1.80) $Date: 1994/09/23 23:30:37 $ >>>>>>>> revised:1995/10/18 by: yav translated by: ITO Takayuki Edited by: Hitoshi Ozawa DISCLAIMER KISS General Specification is public domain and is provided free of charge to all users on an AS IS basis without warranty of any kind, including without limitations the fitness of this specification to your needs. The entire risk of using and developing software based on this specification is borne to you. IN NO WAYS WILL DEVELOPERS AND AUTHORS OF THIS SPECIFICATION BE LIABLE TO YOU OR ANY OTHER PERSON FOR ANY DAMAGE OR LOSS FROM CONTENT OF THIS SPECIFICATION. Content of this document is subject to change without notice. Furthermore, there are topics that are not still not fully defined in the KISS specification. They will be covered as they are defined. *********************************************************** 1. Introduction KISS is a paper doll program came to existence on March 1991 when it was initially developed to run on Japanese NEC PC-9801VM2 computer. The initial program was dependent on the NEC computer architecture but due to its popularity, it was soon appearing on other platforms. To help further spread KISS, this KISS data format reference manual, KISS General Specification : KISS/GS containing the most recent specification, was written as a PUBLIC DOMAIN document. This new specification was developed to be independent of NEC computers and portable across all computers platforms. 2. Changes in Specification New specification is fully upward compatible with the old specification. However, following limitations have been changed: OLD NEW * color (cel) 16 colors -> 16 or 256 colors * color (palette) 4096 colors -> 4096 or 16,777,216 colors * screen size 640 x 400 -> 768 x 480 or more * maximum number of 128 -> 256 or more cels and objects Furthermore, the multiple color palette files are now supported. (Refer to section -> 4-1 Multi-Palette) With this change, a header containing necessary information are now inserted in cel and color palette files. All these changes, nevertheless, may actually be limited during implementation by hardware and software specifications. To distinguish these levels, KISS/GS specifies the following levels: KISS/GSn (where n = 1,2,3,... ) (Refer to section -> 7 KISS/GS Levels) 3. Basic Concepts 3-1 KISS functions KISS is an image viewer program supporting transparency processing and display object layering. To enable it to be used as a doll clothing changing program, these objects are made to be moveable in real-time using a mouse. 3-2 Files KISS uses the following files: * Cel file Cel files (files ending with CEL extensions) contain images of individual pictures. It consists of array defining each color of a pixel (color code) with the first pixel (0th pixel code) defining the transparent color. * Palette file Defines relationship between the color code used in the CEL file with the actual screen color code that is used to display them. Maximum of color palettes for 10 settings may be defined. * Configuration file Defines the cel layer ordering and coordinates. This is the first file KISS opens to find what other files need to be opened. Configuration files, also, are ordinary text files that may be created with a text editor. Some KISS program may update some definitions when [Save] is selected. 3-3 Glossary of Technical Terms * Cel Minimal picture element manageable by KISS * Object Unit of moveable pictures. Composed of one or more cels. * Palette group Color information pertaining to a screen. * Set Group of palette group and object coordinates. 4. GS-KISS Special Feature 4-1 Multi-palette Standard computer system only support one color palette. KISS, by supporting several colors palette files, lessens picture elements dependencies. Thus, parts like clothes and accessories may exist individually as a separate file (cel file). These parts may be paired with a background to create a complete picture. Furthermore, because each piece of a picture may have independent color palette, they may be created by different developers. However, each cell must specify which color palette to use. The only limitation that exists now is that the total number of color must be less than or equal to 256 colors. 5. Configuration File Each line in a configuration file must be shorter than 256 bytes. Furthermore, cel and palette filenames must be composed of basename (max 8 bytes) + extension (max 3 bytes) with upper and lower cases characters treated identically (MS-DOS limitations). Characters that may be used in filenames are [_0-9a-z]. The first character of each line specifies the content of the line. Character Content * '=' Data memory size in kilobytes Format: =K Specifies how much memory to allocate for KISS data. Is used in KISS v1.0 for compatibility but is ignored by KISS v2.0 or later. Usage is discouraged. Example: | |=260K | * '(' Screen size Format: (,) Defines screen size. When omitted, KISS v2.18 compatible size of (448,320) is assumes. Maximum screen size supported by KISS/GS2 is (640,400). (Refer to section-> 7 KISS/GS Ranks) Example: | |(640,400) | * '%' Palette filename Format: % Defines palette files to open. Several palette files may be defines. When they are, they numbered 0,1,2... in order of usage. All colors defined in the first palette file are used, but the first color (transparent) color in the remaining files are ignored and palette are shifted left one place. Additionally, the total number colors defined by all file palettes must be less than 256 colors. Furthermore, all color palette files must be defined prior to cel file definition. Example: | |%COL.KCF |%COL2.KCF | * '[' Border color Format: [ Defines the color of screen where color is not explicitly defined by the cel data. Pixel code is the color code defined in the cel file. Example: | |[12 | * '#' Cel file Format: #[.] [*] [:...] where : Unique ID number to specify an object. Cels with a same Mark are combined as an object. KISS/GS2 supports Marks between 0 to 255. (refer to section -> 7 KISS/GS Ranks) : A number indicating object movement fluidity. Usually used to fix an object to a location. A number from 0 to 32767 may be specified with larger number requiring more operations to move an object. When omitted, an object is assigned a value of 0 (ie. totally mobile). : Specifies the cel file name to assign to the Mark. : Specifies palette file corresponding to the cel file when multiple palette files are defined. When omitted, palette file 0 is assigned. : Assign an object to a particular set. There may be 10 sets which are numbered from 0 to 9. When omitted, an object will become available in all sets. Cels are layered in order of definition with first definition being the top layered cel and last being the bottom layered cel. Up to 256 cels may be defined in KISS/GS2. (refer to section -> 7 KISS/GS Ranks) Example: | |#2 data1.cel ; top (shown in front of other cells) |#3 data2.cel :2 3 4 ; available only in sets 2,3,4 |#4.255 data3.cel ; fix object location |#5 data4.cel *1 :5 ; use palette 1. only in set 5 |#2 data1_.cel ; bottom (shown behind other cels) | In the following example, data1.cel and data1_.cel are combined as an object. * '$' Set Information Format: $ [ ...] Defines palette group and position of objects in each set. Up to 10 sets, numbered from 0 to 9, may be defined. Set Information section are usually automatically generated when [Save] is selected from KISS so there probably isn't any need to directly modify them. When definition extends through multiple lines, continued rows start with a space. : Palette group number. 0 - 9. : Position of object (ordered in accordance with Mark definition). KISS/GS2 supports up to 256 positions definitions. (see also section -> 7 KISS/GS Ranks) Undefined objects are denoted by an asterisk (*). 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 * * * | 16,355 394,362 108,355 * * * 125,261 |$0 192,11 * 56,176 55,21 259,62 15,24 375,63 | * ';' Comment Format: ; Igonores content of this line. Future KISS/GS versions may specify to enable some information such as title and author names in comments lines to be a read into a program. * Others Reserved for future extensions 5. Cel File Layout In new KISS/GS, cel files each contain a 32-byte header. offset size contents +0 4B KiSS data Identifier ( 4Bh 69h 53h 53h ) +4 B cel file Mark ( 20h ) +5 B number of bits to represent a pixel (either 4 or 8 ) +6 W Reserved +8 W(L,H) Width ( 1 ... XMAX ) +10 W(L,H) Height ( 1 ... YMAX ) +12 W(L,H) x-offset ( 0 ... XMAX-1 ) +14 W(L,H) y-offset ( 0 ... YMAX-1 ) +16 16B Reserved WARNING: All reserved fields must be filled with 0. Cels defined in the same object are aligned by their top left corners. When offsets are defined, a cel are moved to coordinate (x,y) from this top left corner. +32... Pixel data * Data Layout of 4 bits per pixel data (16 colors) -when bit 5 in the header is 4 One raster layout: |<- byte ->| |<- byte ->| |<- byte ->| MSB LSB MSB LSB MSB LSB | pix0 | pix1 | | pix2 | pix3 | | pix4 | pix5 | ......... | pixN | When there are only odd number of pixels in a line, the end pixel is padded with a '0'. Pixel data consists of concatenation of these arrays defining each line in a cel. * Data Layout of 8 bits per pixel data (256 colors) -when bit 5 in the header is 8 One raster layout: |<- byte ->| |<- byte ->| |<- byte ->| MSB LSB MSB LSB MSB LSB | pix0 | | pix1 | | pix2 | ... | pixN | Pixel data consists of concatenation of these arrays defining each line in a cel. An old KISS format may not have 'KiSS' in the first 4-byte identification field. In such a case, the file layout is as follows: offset size contents +0 W(L,H) Width +2 W(L,H) Height +4... Pixel data Pixel data are in the 4 bits per pixel data (16 colors) format which is the same as those defined above. Furthermore, x and y offsets should both be treated as 0 (ie. no offset). 6. Palette File Layout Palette files have a 32-byte header. offset size contents +0 4B KiSS data Identifier ( 4Bh 69h 53h 53h ) +4 B Palette file mark ( 10h ) +5 B number of bits per color ( 12 or 24 ) +6 W Reserved +8 W(L,H) number of colors in one palette group ( 1 ... 256 ) +10 W(L,H) number of palette groups ( 1 ... 10 ) +12 W Reserved +14 W Reserved +16 16B Reserved WARNING: All reserved fields must be filled with 0. +32... Palette data * Palette Data Layout (12 bits = 4096 colors) -when bit 5 in the header is 12 Each color is defined by 4 bit primary colors - red, green, and blue - in the following 2 byte layout: |<- byte ->| |<- byte ->| MSB LSB MSB LSB | rrrr | bbbb | | 0000 | gggg | .... When there are less than 10 palette groups, group 0 data are replicated to fill to form 10 groups. * Palette Data Layout (24 bit = 16,777,216 colors) -when bit 5 in the header is 24 Each color is defined by 1 byte primary colors - red, green, and blue - in the following 3 byte layout: |<- byte ->| |<- byte ->| |<- byte ->| MSB LSB MSB LSB MSB LSB | rrrrrrrr | | gggggggg | | bbbbbbbb | ... When there are less than 10 palette groups, group 0 data are replicated to fill to form 10 groups. An old KISS format may not have 'KiSS' in the first 4-byte identification field. In such a case, the file layout is as follows: +0... palette data Palette data are in the 12 bits per each color with 16 colors in a palette groups with 10 groups. Refer to Palette Data Layout above for palette data layout. NOTE: KISS data identification purposely consists of lower case 'i' to reduce possibility of conflicting with other file formats. 7. KISS/GS Levels Rank size colors max cels Status --------------- ---------- ---- ---------- KISS/GS1 640 x 400 16 128 ; KISS v2.24c KISS/GS2 640 x 400 256 256 ; KISS v2.37 KISS/GS3 768 x 480 256 256 ; draft KISS/GS4 768 x 480 256 512 ; draft --------------- ---------- ---- ---------- Degree of data portability was increased with generalization of specification. Nevertheless, differences in hardwares still limits some computers from running KISS programs and displaying KISS data. Above ranks are specified as a guideline to allow developers to write programs and for users to display data on their platforms. We encourage programmers to implement the highest KISS rank capable on their system and for users to use highest ranks program to view them while keeping in mind that the lower ranks have more users base. * Miscellaneous This document is in public domain. Please send bug reports, questions, comments and problems to UHD98984@pcvan.or.jp yav Thank you.