Document

This is some basic documentation for Archimedes KISS v1.96, a freeware release of a non-desktop KISS viewer. See "Readme" for further info on KISS and "Archives" for some info on KISS archives.

If you have problems loading a KISS config then the program gives an error message and offers to exit the KISS program, "Y" or "y" causes it to exit, any other character to continue, so a lot of errors can be stepped though by tapping the space bar. It should not be possible to damage anything by not exiting the program on an error, but as a last resort tapping ESC twice should force an exit. Brave people can load the program into BASIC and use "PROC_Display_Sets" to re-start the program to avoid re-loading a config after an error.

This program is useless without KISS archives to view, and some way to access them as they are in PC LHA (.LZH) compressed archive format. !SparkPlug will do for this, as will LHA running on the PC Emulator, !SparkFS is probably the best solution, but costs 25 quid! Alternatively get a PC user to de-compress them for you and use !MultiFS on RISCOS 2, or the standard FS on RISCOS 3, to read the PC discs.

By default the current directory is searched for a KISS config file called "KISS" (or "KISS.CNF", or "CNF/.KISS") and the current directory is expected to contain the palette and all the cel files refered to in the config file. This can be achieved by renaming or copying the config file to "KISS" if is not called this (or changing "KISS" on line 120 to whatever appropriate), and using a utility like !ClickDir (or the CLI "Dir" command) to set the current directory. This technique was used throughout the development of this program.

Even though cels have names "<filename>.CEL" the program also checks in "CEL/.<filename>" to allow full 8+3 PC filenames to be accessed heirarchically (i.e. use the extension as a directory name) on MultiFS or ADFS. Note that "KISS/CNF" and "<filename>/CEL" are also checked for to give compatibility with some PC filing systems.

There are a number of system variables checked for which can be used to control KISS:

KISS$Config - if exists must be the filename of the KISS config file to use,
              e.g. "NADIA1E.CNF"; if not used the default is "KISS"
KISS$Load   - if exists is used to prefix all file loads, including the config file,
              e.g. "ADFS::0.$.KissData."; if not used the default is ""
KISS$Save   - if exists is used to prefix all file saves, including the config file,
              e.g. "ADFS::0.$.SaveKiss."; if not used the default is "ADFS:"

KISS$Advanced   - if exists enables advanced screen controls
KISS$MemorySize - if exists must be the memory size for KISS in kbytes,
                  e.g. "2048", if not used the default is "1536" (usually enough)
KISS$ModeText   - if exists sets text  screen mode; default is  0
KISS$ModeImage  - if exists sets image screen mode; default is 20

KISS$Translate  - if exists displays filename translations; ALL of them!
KISS$Silent     - if exists dont display anything except an hourglass;
                  ignored by Translate and Debug
KISS$Debug      - if exists display cel name and XY during cel step

System variables may be set using the CLI "Set" command, e.g.

*Set KISS$Config "CHIP.CNF"

Note that simply setting a variable to "" does not get rid of it, the CLI "Unset" command must be used, e.g.

*Unset KISS$Config

You can see the current values of the KISS system variables by using the CLI "Show" command, e.g.

*Show KISS$*
kiss$advanced : 1
kiss$config : moe
kiss$load : sparkfs#adfs##4.$.wks_moe:$.

this example shows the values for use of advanced mode, and assumes the KISS archive "WKS_MOE.LZH" has been copied into the root directory of an ADFS harddisc with the name "WKS_MOE" (possibly using !MultiFS in heirachical mode), that "MOE.CNF" is the name of its config file, and that !SparkFS has been loaded and is on the icon bar. If this is the case then running KISS will display Moe without needing even to decompress the LHA archive.


*Set kiss$advanced 1
*Set kiss$config moe
*Set kiss$load sparkfs#adfs##4.$.wks_moe:$.
KISS

this example Exec file will run KISS on "WKS_MOE" as long as it is set up as above, and KISS is in the current directory or the library.

If you cant get KISS to run on an archive then there is often something wrong with the setting of kiss$config or kiss$load. The easiest way to find out about this is to use CLI command "Set KISS$Translate 1" and see if the filename translations displayed look ok (a space on the end of kiss$load really messes you up); this will fix 99% of problems (touch formica). Remember to use CLI command "Unset KISS$Translate" afterwards, or you will get a lot of extra (but not harmful) output.


The program is designed to be mostly run by the numeric keypad, 0-9 selecting the set to be displayed, and operators selecting some of the more common commands. Otherwise "?" provides help, "\" gives access to the command line, and "Q" exits the program. At the moment the cursor control and function keys are not used.

If not in advanced mode then the help screen, accessed by pressing "?", will, after clicking the mouse over a movable object, look something like this:



                      Help Screen V1.96

Commands:
#:        Save set as file Set<n>, e.g. Set0, Set1, Set9
\:        Command line input, until blank line
* S s:    Save config as file <Fname>.CNF, default KISS, e.g. KISS.CNF
C c:      Save Current Mark (if any) as file <Fname>.SPR, default CEL
L l:      List cels: A(ll) S(et) C(urrent) O(bject)
? H h:    Display this help screen
Q E X:    Quit, Exit, eXit KISS program; all the same effect (also qex)
q e x:    quit, exit, exit KISS program; all the same effect (alse QEX)

Status:
Config=   moe.cnf
Palette=  MOECOL.kcf
Set=      0
Cel:      XY=509,254 REI.CEL
Cels=     106
Max Mark= 55

Press any key to continue


If in advanced mode it would instead look like this:



                      Help Screen V1.96

Commands:
#:        Save set as file Set<n>, e.g. Set0, Set1, Set9
\:        Command line input, until blank line
* S s:    Save config as file <Fname>.CNF, default KISS, e.g. KISS.CNF
C c:      Save Current Mark (if any) as file <Fname>.SPR, default CEL
L l:      List cels: A(ll) S(et) C(urrent) O(bject) F(ix)
? H h:    Display this help screen
Q E X:    Quit, Exit, eXit KISS program; all the same effect (also qex)
q e x:    quit, exit, exit KISS program; all the same effect (alse QEX)

Advanced Commands:
+:        Off-screen re-paint of sets ON
-:        Off-screen re-paint of sets OFF
.:        Cel step re-paint ON (also Off-screen re-paint OFF)
,:        Cel step re-paint OFF
/ F f:    Fix level set to <n>, 0-32767, default is 0
W w:      White background ON, until click or new set

Status:
Config=   moe.cnf
Palette=  MOECOL.kcf
Set=      0
Fix Level=0
Cel:      XY=509,254 Fix=0 REI.CEL
Cels=     106
Max Mark= 55
Fix Levels 0 500 80 120

Press any key to continue


The difference between the two modes is the increased range of commands available, particularly the "/" command to allow the program-wide fix level to be changed to allow objects to be moved that would otherwise be fixed down. This allows a restricted or "viewer" version of the program, possibly for educational use. "Fix Levels" gives fix levels used by all objects, there is no point in setting the fix level to other than these. Use of this with the various "L" commands should give a clear understanding and full control of all objects.


The "#" command does a screen dump of the current view on the screen.

The "*" command saves the current set positions as a new config file, possibly over-writing the old one. If this is to be saved on ADFS then a directory "CNF/" must exist in the current or specified directory to save the config in.

The "C" command saves the currently selected object as one or more sprites in a sprite file. If this is to be saved on ADFS then a directory "SPR/" must exist in the current or specified directory to save the object in.

The "L" command lists the details of cels, modified by various suffixes: "LA" list all cels, "LS" and "LC" lists the current set's cels, and "LF" (only available in advanced mode) lists cels with the current fix level. The current set, mark, and (in advanced mode) fix level is also listed, and "LF" also lists the fix levels. The default for the "L" command is "LA", so for example "L " will list all cels.

The "W" command temporarily sets the background colour to white, this makes converting screen dumps into grey-scale artwork with a white background suitable for use in magazines far easier (use !Translatr with "Process/Colour/Black & White" and "Process/Colour/Expand range" for good results).

The "." command single-steps the drawing of the set, so as to see how it is constructed. To go on to the next step press " ", if "," or "-" is pressed single-stepping stops, if "#" is pressed then a screen dump is done.


Note this program does not support the alternative background colours of normal KISS, and the mouse interacts with cels in some interesting ways, allowing click-drag to "fish" for movable objects, and allowing the selection of movable objects hidden behind immovable ones. Also as long as some part of an object is movable then it may be used as a "handle" to move an otherwise immovable object. The other major difference from standard KISS is that repeatedly clicking objects does not make them more movable, the only way to do this is to alter the program-wide fix level (using the "/" command), only possible in advanced mode.

This version of KISS seems to be reasonably stable and bug-free. Some support for the new KISS/GS standard has been added, but this is not complete, e.g. the multiple palette handling.

To Do List for V2:

Add (object) editing facilities (Z-coord, fix, mark)
Add sprite alternative to cels in config "<filename>.SPR", multi-load?
Add dynamic sprite load to object facility
Improve re-draw speed by selectively redrawing cels
Implement full-screen desktop version
Implement full scrolling desktop version (ha!)


R.O.McLean, 05/Nov/94
hurom@hpb.lut.ac.uk
