U7 Wizard 1.9 file

Welcome to U7 Wizard 1.9 - The Ultimate World & Scenery Editor for U7 Games
Copyright © 1999 by Olivier Marcoux. All rights reserved.
http://www.pulsar.eu.org/wizard/ultima/u7wizard.htm

************************************************
This program allows you to view and edit components of the "Ultima VII" games
This includes: The Black Gate & Serpent's Isle
This software has been widely tested on Serpent's Isle but should work fine
with The Black Gate. Please report bugs or ideas to u7wizard@pulsar.eu.org
This software is Shareware. If you like it, please send me 15$.
Contact me to get my postal address: u7wizard@pulsar.eu.org

************************************************
SCREEN OVERVIEW

the screen is divided in two :
-left is the view, depending on the mode you're in
-right is the bar showing common and specific informations as
  well as the list of available commands or choices
You will often find the following information on this bar:
-X=xxx and Y=yyy coordinates (in hex format)
  This can be used to teleport with the cheat mode of the game
  It depends on the location of the mouse. if the mouse is not
  in the view, this is the coordinates of the center of the view
-REGxx
  This is the region number (in hex format) matching the coordinates
  This can be used to know which U7IFIX & U7IREG file is used
-Chunk=xxx
  This is the number (in hex format) of the chunk under the mouse
  A chunk is a piece of map that can be use several times.
  It is 16x16 large (the size of a one-room house)
  It is composed of tiles (flat floor) or basic shapes (walls, moutains...)
-Shape=xxx-yy-z
  This is the reference number (in hex) of the shape/tile under the mouse.
  xxx is the type. yy is the frame. The meaning of z is unknown yet
  You can use xxx and yy in the cheat mode with "create item"
  Note: To select shapes that are not flat, you should click on their
  "hot tile". This is the tile that created them. It is usually the
  most bottom-right tile covered by the shape
  Under the shape you will find the description of the shape.
  This makes it easier to select the shape you want
You will often find the following command on the bar:
-ESC:exit
  This should always works
-S:view shapes
  Pressing S activates the "View shape" mode
-M:view map
  Pressing M activates the "Entire Map" mode
-P:palette (x)
  Pressing P cycles through the palettes of the game
  The number of the current palette is shown there
  Pressing Ctrl-P allows you to choose a palette from a .PAL
   file in the STATIC directory
-F3:full screen
  This toggles the current mode to full screen view
  or standard view with bar
-F:find item
  You can find an item in the whole world given its shape type and/or
  frame and/or quality. 
  If you're in Shape Viewer or any other Shape Chooser, pressing F
  allows you to find an item given its name
-T:teleport
  An easy way to jump to given coordinates
-N:teleport to NPC
  An easy way to jump to the given NPC
-F6:editor
  This switch the current mode to the corresponding editor/viewer.
Some of these command works even when they do not appear, so try them

************************************************
MODES LIST

Warning: If you want to modify the map, be sure to know what you're doing.
  This could damage your map. No cancel available.
  The Ctrl Key is required to be held on in some cases for security.
  I'm not responsible for any damage caused by the use of U7Wizard
  You may want to make a backup of the STATIC & GAMEDAT directories before editing

Mode "Entire Map":
You see the whole map of the game. One chunk = One pixel
Click anywhere with the left button or press "+" to zoom in
On your right, you see a small "zoomed map"-like view of the
current coordinates.

Mode "Zoomed Map":
You see a zoomed portion of the map. One chunk = 16x16 pixels
Click the right button or press "-" to zoom out to entire map.
Click anywhere with the left button or press "+" to zoom in
Use the arrows,PgUp/Down,Home,End to scroll the map
Press F6 to switch to mode "Edit Map"
Press F3 to switch to full-screen mode

Mode "Game View":
You see a view similar to the game. This is a 100% zoom
I will keep trying to find a better algorithm.
If you find one, please contact me.
One chunk = 16x16 tiles/shapes. One tile = 8x8 pixel
Click the right button or press "-" to zoom out to entire map.
Click on a tile/shape with the left button to view it in mode "Shape View".
(Only the floor tile/shape are concerned by this click)
Use the arrows,PgUp/PgDn,Home/End to scroll the map
With F7,F8,F9 you can show/hide the items that are not part of the basic floor
This includes static (fixed) items, game (user interactive) items and NPCs.
Press F5 to switch to mode "Edit View"
Press F6 to switch to mode "Edit Chunk"
Press F3 to toggle the full screen view
Press F2 to toggle the clip mode. The clip mode determines whether
shapes (non-flat items) that are offscreen are drawn or not.
Use "K" and "L" to choose the lift limit which defines what items should
not be shown, depending on their lift level.
The rendering system has been improved but is not completely perfect compared to the game.

Mode "Shape View":
You see either a table of the different frames of the shape
or if the frames are too large, only the current frame.
A shape can have many frames which are different drawings for
the same type of object. For example, the shape "tree" has 4
frames that paint the differents tree available.
Click the right button to go back to the previous mode
Press "+" or "-" to cycle through the available frames
Press PgUp/PgDn,Home/End to cycle through the available shapes
Use the arrows the change the gap between the frames in the table.
If the table doesn't fit the screen, only the current frame will be
shown. To view the frames as a table, you can either switch to full
screen view (F3) or use the arrows again to reduce the gap between frames
On the bar you can see the X,Y dimension of the shape (number of tiles),
the weight/volume of the object (in 0.1 stone - stone is the unit used the
inventory screen)
You can also see the current frame. If you see a table of frames, this is
the number of the first frame. If the mouse is on a frame, this is the
number of this frame
Press F4 to change the file to view the shapes from. (default=SHAPES.VGA)
You can select any FLEX/FORM_INTR file from the static directory
A FLEX file is a collection of objects used by the game (shape, palettes,
musics, texts...)
An FORM_INTR file is a collection of files used for the intro/endgame (video,
speech...)
The shape viewer is able to detect the type of the object and can show
shapes, palettes and texts.
In any case, you can use F5 to save the current object in a file. This can
be useful for example to listen to VOC speech, MID music or to view a FLIC
animation.
Press F6 to edit the shape properties

Mode "Zoomed Map Editor":
It look like the mode "Zoomed map" except you cannot scroll the map
Instead the arrows, PgUp/PgDn,Home/End allows you to select the type of
chunk you wish to use. The number of the selected chunk is shown.
Right click on the map or press F6 to exit to mode "Zoomed map"
You can left click on the map or on a chunk to switch to "Edit Chunk" mode
You can right click a chunk on the bar to select it.
To place the selected chunk on the map, press the Ctrl key and right click
on the map.
Note: Modifying a chunk won't remove non-floor-level items from the game view.

Mode "Chunk Editor":
It look like the mode "Game view" except you cannot scroll the map and you
edit only the floor tiles/shapes.
Right click on the map to zoom back to "Map Editor" mode
Press F6 to exit to mode "Game View"
You can left click on a shape/tile to view it in "Shape View" mode
When you place the mouse on a shape/tile, it is shown (even if it
should be hidden by another shape) and surrounded by flashing volume
that shows the dimension of the shape.
On the bar, you can see the number of this chunk and the number of
times it is used in the whole map
To find another match of this chunk on the map, press F7.
Use the arrows, PgUp/PgDn,Home/End to select the tile/shape you
wish to use. Use F10 to change the shape direction.
Pressing the Ctrl key will show you the selected tile/shape.
Right clicking while pressing Ctrl place the tile/shape on the chunk.
Only chunk items appears here.
Tip: if you left click while pressing Ctrl, you view the selected shape
 in "Shape View" mode. Exiting "Shape view" mode with right click
 will remember the shape you chose in this mode.

Mode "Items Editor":
It is similar to the mode "Game View" except that a blinking blue box
is surrounding the floor tile/shape you're on and all items placed on and
above this tile are also shown and surrounded by a box.
On the right bar, you can see the name of these items and their lift level
Use "+" or "-" to select an item or click on the floor tile and then use the
mouse to select an item. Once selected, details will appear at the bottom.
If the item is a special item (Egg, Container...) you can click on its name, this will
bring the appropriate Editor, otherwise it will bring the shape viewer.
Press Ctrl and click on its name to modify/move it using the "item chooser".
Press F10 to create and place a new item using the item chooser.
Select an item name and press Del to remove it from the map.
Hint: Using "+" to get the detail of an item won't move the mouse cursor.

Mode "Egg Editor":
Here you can view and edit the details of the egg.
The informations displayed here depends on the type of egg.
These are similar to the one you can get with the F9 key in
the game using cheat mode
Press "M" to modify the values. You will be prompted to enter
each value. Press Esc or Enter if you don't want to change the
value. Use the arrows to select another value.
When prompted for numeric values, type the decimal digits and Enter

Mode "Container/NPC Editor":
Here you can view and edit the content of the container.
If you're editing an NPC, his/her face is displayed at the bottom.
On the left, you see the picture of the items contained.
On the right, you see their names.
If one of the item is an Egg or another Container, you can
click on its name to view this item.
Select an item and press Del to remove it
Use F10 to add an item in the container with the "item chooser"
Press P to view/edit the container/NPC properties

Mode "Shape/Item Chooser":
This allows you to choose the location for an item and to change its type.
Use the mouse to select the location. Move the cursor near the border
of the screen to scroll the map.
Use the arrows, PgUp/PgDn,Home/End to select the type & frame of the shape.
Use F10 to rotate the shape.
Use +/- to change the lift of the shape. 
Press Q to change the quality of the shape (if applicable)
When done, click the choosen location. You need to hold Ctrl
if you're creating a new item. In the container item chooser, press
Enter when you're done.
You can cancel by Right-clicking or pressing Esc.
A red name refers to a container. A green name refers to an Egg.
A gray name refers to a static item.
When editing an NPC you can only choose blue names that refers to NPCs
All other name refers to game items. Chunk items are not shown.

Mode "Container Properties Editor"
Here you can change the kind of container (standard, trapped, dead npc)
and some properties like "invisibility" and resistance to attack/lockpicking
Press M to modifiy

Mode "NPC Properties Editor"
Here you can view/edit the whole list of properties for the given NPC
Most of them are accessible using the cheat mode in the game
You can use PgUp/PgDn/Home/End to view another NPC's stats.
Note: if the NPC face is grayed out, it means that it might not be the adequate face for the given NPC.
Press N to change the name or M,O,P to modify each column of properties
Note: You can change properties/schedule either with U7Wizard or using the cheat mode of the game

Mode "Shape Properties Editor"
Here you can view/edit the whole list of properties for the given shape
This includes dimensions, kind, animation and other flags.
Here you can also load a shape from a file which must have the same format as the file you get
when you press F5 in the Shape View. This way you can use an external shape graphic editor.
Press N to change the name of this shape

************************************************
COMMAND-LINE FEATURES

These are feature you can only access using the dos command-line options

Game extractor:
U7WIZARD.EXE -EXTRACT <game archive> <destination dir>
extracts the files in the game archive into the destination directory
the game archive can be the GAMExx.U7 file or the STATIC\INITGAME.DAT
which contains a new game from scratch

Init Game maker:
U7WIZARD.EXE -BUILDINIT
compulse the GAMEDAT directory into an initial game archive that can be
use in place of the STATIC\INITGAME.DAT file. This can be use to create easily add-ons
for Ultima.

Data integrity checker:
U7WIZARD.EXE -CHECK
check for various file integrity

Map picture generator:
U7WIZARD.EXE -MAP <destination dir>
generates a MAP.BMP picture file of the full map similar to what you get in Zoomed Map mode
This is a 3072x3072 8-bits standard Windows bitmap file.
Warning: It is 9 Mb large ! Make sure you have enough free disk space...

Usecode disassembler:
U7WIZARD.EXE -DISASM <function number> <destination dir>
disassembles the given usecode function and produce an assembler source file with a name like xxxx.TXT
The game engine use a stack-based machine with local variables and arguments for each function
The opcode are easy to understand for someone who already know some assembly language:
jtrue/jfalse: branch if boolean (or integer) on stack is true (non-zero) / false (zero)
jmp: relative jump
add/sub/div/mul/and/or: perform an operation on 2 integers (or string for "add") on stack and push the result
not: perform the operation on 1 integer on the stack and push the result
pop/push true/push false/push ref/push event: pop or push a value ("ref" is the ID of the current item, "event" is the reason of the call)
test: perform the given comparison on 2 integers on stack and push a boolean result ("in" checks if a value is in an array)
concat: concatenate the given value to the current string register to be displayed (or SAYed)
array: create an array from the given amout on values on stack
arryadd: create an array from the given first value on the stack added at the end of the second array on the stack
get: extract a value indexed by the integer on stack from the local array variable
put: replace inside the local array variable a value indexed by the first integer on stack by the second value on stack
call/ret: classic function calls (some functions may return one value on the stack)
calli/callis: external function calls for native functions in the game engine (callis return one value on the stack)
pop result: pop a value on the stack as the future return value
ret result: returns from function and push the return value on the stack
abort: immediately abort the function and all ancestors calls
say: display the current string register to the user
sloop/loop: start of loop to cycle through the values of an array
The disassembler does not recognize every opcodes as some are unknown for the moment

Usecode decompiler:
U7WIZARD.EXE -DECOMP <function number> <destination dir>
decompile the given usecode function and produce a C-like source file with a name like xxxx.C
The C++ like operator << does a concatenation on string or array
"cout" receive the future string to be SAYed with cout::say();
The implicit "result" variable receive the value to be returned by the function with "return result;"
The global variable "flag" is a bit array that defines the game flags
Aborting the function calls is done with "halt(0);" or "halt(1);"
The "for" syntax defines a loop through each value from an array in a local variable:
"for (A in B index C max D)" means that A will be assigned each value from array B, C will receive
the integer index of the value (1-based) and D receive the number of value in the array
function names beginning with a "_" are external native function from the game engine.
other functions are usecode functions.
The decompiler may not work properly with some functions and you will get a truncated source code or an error.
In these cases you can still use the disassembler.

Warning: the external functions differs in Ultima 7 (The Black Gate) and Serpent's Isle
Notes: negative numbers are often NPC identifiers

The EXTERNAL.DAT file:
contains 3 sections to help the disassembler/decompiler to find a better name when displaying function calls:
** EXTERNALS <game engine>   game engine is the name in IDENTITY: ULTIMA7 or SERPENT ISLE
xxxx yyyyyy                  xxxx is the external function number, yyyy is the name to be used
**                           marker for end of section
** FUNCTIONS <game engine>
xxxx yyyyyy [z1 z2...]       xxxx is the usecode function number, yyyy is the name to be used
**                           z1,z2 are the name to be used for the parameters and local variables (decompiler only)
** CONSTANTS <game engine>   (for decompiler)
<event>
#define name value           replace the given integer value with the name in a comparison with "event"
<*>
#define name value           replace the given integer value with the name anywhere else
**


************************************************
Notes:
VOC speech files can be played by WinAmp and CoolEdit
MID music files can be played by Windows Media Player
FLIC animation files can be viewed with PLAYFLC (included in the archive)

U7Wizard is handling the U7IBUF caching system of the game engine. This means that you can
modify objects in U7Wizard even if they are close to your party. Reversely, you can move objects
with the game using the cheat mode and the changes will appear in U7Wizard.

Available in future releases:
-NPC schedule editor
-overall map editor
-usecode assembler/linker
-graphics editor


If you have informations about the following files, please contact me:
  STATIC\OCCLUDE.DAT    STATIC\READY.DAT
  STATIC\TFA.DAT        STATIC\WIHH.DAT
  GAMEDAT\*.DAT

More technical descriptions of the files used by the game engine can be found in the
"TECHNICAL REFERENCE AND INTERNAL FORMATS OF ULTIMA7 FILES" at:
  http://www.pulsar.eu.org/wizard/ultima/u7wizard.htm

************************************************
History:
1.9c Fixed MANY bugs, Added World Map generator, Init Game Maker, Full-screen for Zoomed map
1.9b Fixed some bugs, Added NPC properties editor, Data integrity check, 
     no more flickers, shape rotation
1.9  improved display, bug fixes, auto-scrolling screen borders,
     usecode disassembler and C-like decompiler, U7IBUF cache handling
     NPC viewing/editor/teleport, NPC properties viewer
1.8  items add/remove, egg/container editor, find shape by name feature,
     mini-zoom in entire map view, full palette animation, shape properties editor
1.7  find item & teleport features, fixed item's quality & animations bug,
     added egg/container viewer
1.6  items selector, better transparency effect, fixed items-in-container bug
1.5  full map view, chunk editor, recognize .SHP files
1.4  now recognize Intro files (intro.dat/endgame.dat).
     palette can be a .PAL file
1.3  added animations,beta chunk editor,added some functions, 
     better documentation
1.2  added map editor
1.1  fixed minor bugs, first public release
1.0  first release

************************************************
System Requirements:
PC 386 - 320x200x256 screen mode - 640 Ko - Mouse
Can run under DOS & Windows 95/98.
However Smartdrv is recommended under DOS.

************************************************
Thanks to Maxim S. Shatskih, Wouter Dijkslag, Keldon Jones, Jakob Schonberg, Jeff Freedman
for their research on the usecode file

PS:Sorry for my english, I'm french  :-p

Olivier Marcoux
u7wizard@pulsar.eu.org

************************************************
The author cannot be held responsible for any damage or other consequences of
using this software.
This software is not sanctioned or authorized by Origin Systems, Inc.
"Ultima VII", "The Black Gate" and "Serpent's Isle" are registered trademarks
of Origin Systems, Inc.