asylum | Surgeon

Surgeon Manual Thingy

For surgeon V0.09

• What is Surgeon?
• Getting started
• Editing tools
• Editing menu
• Style files
• History
• FAQ

Surgeon is freeware, © Jeffrey Lee 2003

What is Surgeon?

Surgeon is a program for editing Asylum levels, Asylum being a platform game release by Andy Southgate way back in 1994. Asylum is now in the public domain, so if you fancy a copy head over to asylum.acornarcade.com and grab one.

Getting started

Getting started is as simple as double-clicking !Surgeon to load it onto the iconbar. Once there you can load existing Asylum levels by dragging them to the Surgeon icon on the iconbar, or create new ones by clicking on the icon with Select - If you're used to RISC OS then this should be no surprise to you.

Loading an existing level

One area you may trip up on straight away is by dragging one of the applications !Ego, !Id, or !Psyche straight to the Surgeon icon and expecting it to load them. Well don't try that, because it doesn't work. What you should do though is shift-double click !Ego/!Id/!Psyche to display the contents of the application, and look for one of the following files:

• Brain
  This is the big, main level which you start off in
• Neurons.cell1 to Neurons.cell8
  These are the neuron sub-levels containing the shutdown switches

These are the files which you drag to Surgeon, depending on which one you're interested in editing. If you can't find !Ego, !Id or !Psyche then you've probably got a new version of !Asylum which houses them inside itself - Just shift-double click !Asylum to reveal them. Loading of uncompressed and Hammer-compressed level files is supported, but at the moment only uncompressed levels can be saved (Not that this makes any difference to Asylum)

Creating a new level

• Style file
  Enter here the name of the Style file to use, or click on the button next to it to reveal a list of the styles inside !Surgeon.Styles
• Width
  Enter the level width here. The width must be a multiple of 4, and Asylum may have difficulty if you enter a width larger than 256.
• Height
  Enter the level height here. Asylum may have difficulty if you enter a height larger than 256
• OK, Cancel
  The rather self-explanatory OK and Cancel buttons - OK will create the level, and Cancel will close the window

If the new file dialog appears when you try loading a level, then it means that Surgeon was unable to determine the style file to use when editing it. This will be characterised by the file name being shown in the title bar, and the width and height boxes being greyed out. Simply select the style you want to use, or click Cancel to cancel loading the level.

If all goes well you should now have three windows open: The tools window, the palette window, and the editing window. If you go on to load further levels then you'll get an extra palette and editing window for each file.

Closing the editing window will discard that file without any warning, and if you have closed/lost the palette or tool windows then you can use the editing menu to get them back.

Have fun!

Editing tools

This version of Surgeon comes with 7 editing tools: Draw, line, rectangle, filled rectangle, copy level, paint level and copy block.

• Draw
  Clicking/dragging with select in an editing window will draw blocks of the currently selected type in the palette. Using adjust will draw block type 0 (empty space), to erase your mistakes.
• Line
  Click select to set the start point, then select again at the end point to draw a line. Adjust will cancel any current line.
• Rectangle, Filled rectangle
  Operation is essentially the same as the line tool (except with rectangles of course), so I'm sure you can work these out yourself.
• Copy level
  Click select to mark the corners of the new level. The new level will then be based around the data in that rectangle. Adjust cancels at any time.
• Paint level
  Select the level you want to paint with by using the controls in the tools window, then click with select anywhere in any other level to paint with the chosen level.
• Copy block
  Select the rectangle you want to copy, then click at the location(s) you want it copied to. Adjust cancels.
• Step controls
  If these are visible, then they allow you to set the step size that is used to draw lines, rectangles, etc. E.g. when drawing a rectangle of atom bombs (Using an atom bomb macro), an X and Y step of 2 will draw them without any overlapping.
• Transparent control
  For the paint level and copy block tools, this will allow you to use block 0 as a transparent colour - i.e. if this option is selected then only non-zero blocks will be drawn.
• Level selection
  For the paint level tool only. Use the menu icon to open a menu listing all open levels, then select the one you want from the list.

See also the editing menu page, as that contains vital information on zooming, changing the rendering mode, undoing, etc.

You should also see some text at the bottom of the tools window which will give some info on the block currently under the mouse pointer.

Editing menu

When you click menu over an editing window, a menu with the following entries will appear:

• Save
  Leads to a save dialog box for you to save your work. Remember: Keep a backup copy of the original Asylum levels, just in case!
• Show tools
  Open the tools window
• Show palette
  Open the palette window
• Pick block
  Sets the current block to the one under the mouse when the menu was opened. However only blocks listed in the palette can be selected.
• Undo
  Undo the last operation. Multiple undos are supported, but redo is not. The undo buffer should be large enough for most needs, but don't go relying on it since it hasn't been fully tested yet.
• Zoom in
  Zoom in
• Zoom out
  Zoom out
• Draw sprites
  Toggle drawing of sprites
• Draw codes
  Toggle drawing of block codes (In hex). Turning this and draw sprites off will leave you with a blank window.
• Reverse 0
  Reverse the rendering of block zero; i.e. block zero won't be drawn, but any unknown block will be drawn as if it were block zero. Have a play with it if you want, but you'll soon find it's best to leave this option turned on
• Minimal numbers
  Only draw block codes for certain blocks - specifically blocks which do not have palette entries, or blocks which have been flagged as needing numbers in the style file
• Grid
  Toggle grid on/off

Style files

As you should have guessed by now, the core of Surgeon is its style files. These tell it which blocks are what, where to find sprite files, definitions of macro blocks, etc. Understanding the format of a style file isn't necessary to use Surgeon, but it does help.

Style files can be stored anywhere you want, but it's recommended that they are stored in !Surgeon.Styles for Surgeon to be used to its full extent.

Style format

A style file is a plain text file, with a format similar to the following:

# This is a comment
@block_sprites=<PsychoEgo$Dir>.FSPBlocks # This is also a comment
@alien_sprites=<PsychoEgo$Dir>.FSPAliens
0="Empty space"
2>8="Wind tunnel, push left","Wind left"

• Sprite file locations
• Block descriptions
• Macro block descriptions
• Full syntax and other notes

Sprite files

@block_sprites=<PsychoEgo$Dir>.FSPBlocks
@alien_sprites=<PsychoEgo$Dir>.FSPAliens

@block_sprites tells Surgeon where to find the sprite file to use for drawing blocks, and @alien_sprites where to find the sprite file to use for drawing aliens. These files can be in any of the following formats:

• Sprite files (In the same format as produced by nobrainer)
• Fast Sprite 1 files (i.e. the format used in Asylum version 1.00)
• Hammer commpressed Fast Sprite 1 files (i.e. the same as in Asylum versions 2.00 and above)

If you're short on memory then using plain Sprite files is best since Fast Sprite/Hammer files must be converted before use, which can take around 300K of RAM during the conversion. It'll also take less time to load the level, since the conversion code can be a bit slow.

By default, Surgeon looks in the block_sprites file for block sprites. However block codes 240-253 (The codes for the aliens) are hard coded to use sprites from the alien_sprites file; the only way to disable this is to not specify an alien sprites file. Also if you use alien sprites which are different sizes to the defaults then they may be drawn at the wrong locations; this will be fixed in a later version.

Block definitions

0="Empty space"

Tells surgeon that block number 0 has the description "Empty space"

2>8="Wind tunnel, push left","Wind left"

Tells surgeon that block 2 has the description "Wind tunnel, push left", the short description "Wind left" (For display at the bottom of the tools window), and should be displayed with sprite number 8 instead of the default of 2.

97="Standard minigun + spray","Minigun + spray"+m

Says that block 97 is a "Standard minigun + spray", and the +m on the end is a flag to tell it to draw the block code when the 'Minimal numbers' option is turned on.

Macro definitions

256="Gas canister",(0,0)={68},(1,0)={69}

This is a macro block, characterised by:

• The block number being above 255 - Asylum levels are made up of codes 0 to 255, so any block above 255 must be defined as a macro. Conversely, Surgeon will ignore any macros defined for blocks less than 256, and treat them as normal blocks instead.
• It has a list of coordinates and block codes following the description, to define the macros action

The list itself tells Surgeon to:

• Draw block 68 at offset 0,0
• Draw block 69 at offset 1,0

Where 0,0 is the current cursor position, 1,0 is one block to the right, 0,1 one block down, -1,0 one to the left, 0,-1 one block up, etc.

This syntax allows you to define macros for common objects, such as teleporters and lifts. You can also create random macros, where a list of blocks is specified:

282="Random gun",(0,0)={96,97,98,99,100,101,102}

Will draw one of the blocks from 96 to 102, i.e. the minigun weapons. Each entry has an equal chance of being drawn, but you can throw the odds off a bit by listing the same block more than once.

You can also nest macros to build even bigger objects, e.g. the macro definitions for the teleporters make use of the teleporter dome macro:

276="Teleporter dome",(0,0)={4},(1,0)={5},(0,1)={6},(1,1)={7}
277="Up-arrow teleporter (Transports left/up, pairs with down-arrow)",(0,0)={276},(0,2)={192},(1,2)={193}

Watch out though, because you can crash Surgeon if you make a macro reference itself.

Syntax

The exact syntax of a block description line is as follows:

block_code[>draw_as]="description"[,"short_name"][+flags][,(x,y)={block[,block[...]]}]...

Where:

Block codes from 0 to 255 are for 'normal' blocks only, while codes 256 to 511 are for macro blocks only. Currently there is only one flag - 'm', to tell Surgeon to display the block code when the 'Minimal numbers' option is on.

Surgeon allows you to place spaces or tabs between most parts of the descriptor lines, but this hasn't had much testing so it may not be perfect. Also error messages when using Surgeon are rare, so if something goes wrong then it may not be too easy to track down what it is; this should be improved in the next version.

If you're going to try writing your own style file then it's a good idea to take a look at the supplied ones first.

History

V0.09 10/07/2003

• Now 32bit compatible
• A few improvements to my WIMP library may improve performance a bit. In particular, it now won't mess up the machine if you try running it from the command line

V0.08 09/02/2003

• It will now warn you about edited files before closing them, and it now handles missing style files properly instead of just quitting
• A few improvements to my WIMP library may improve performance a bit

V0.07 17/01/2003

• First released version, since it's the first version worth releasing
• Has support for multiple open files, undo buffers, various rendering options, draw/line/rectangle/filled rectangle editing tools, level copying/painting, sharing of sprite files to reduce memory consumption, auto-style chosing, support for Hammer compressed level files, and Hammer compressed FastSprite/Sprite format sprite files
• Some bits of code seem to be a bit slow, so don't be surprised if it acts sluggish at times

FAQ