
************************************
* CANIMATE.VBX -  Release 1.00     *
*     (c) Componere Software       *
*     - All Rights Reserved -      *
************************************

On downloading this VBX, you should have received:
CANIMATE.VBX  <- A BETA level release of the animation control library
GAME.EXE  <- VBRUN200.DLL required to run
GAME.MAK
GAME.FRM
BIRD.BMP <- A 3x2 matrix for cell animation
README.TXT

The "game" is a demo of a hero-type player walking back and forth across 
the stage. A fire is burning in the middle of the stage and every time 
he walks through it, he hops around a bit. A bird flits about overhead,
flying in random patterns to demonstrate varying slopes of travel. The
clouds moving overhead are in a control array, update at lesser intervals
and move less on each update. The two trees at the bottom demonstrate
Zposition; one is in the foreground, one in the background.

Overview
--------

CANIMATE will allow animation controls to be created and manipulated in 
Visual Basic. In the current release, only 2D animation is supported.
There are two types of animation supported: sprite and cell animation.
They may be used concurrently or separately. Sprite animation is moving
an image about on the screen. Cell animation uses frames, or pictures 
of the same thing in various states of motion, much like a motion 
picture. Combining the two techniques results in a much more realistic
mode of animation than either technique alone. A bird can beat its wings 
as it flies about the screen, for example. Sometimes only one is needed;
a fire stays in one spot and flickers, while an arrow flies without ever 
changing its shape.

CANIMATE accomplishes this through the use of two controls: Stage and
Player. Stage is the background, a container in which Players are
created. Players are animated (or not; they can be simply still 
pictures) objects to be displayed on the background.

The Stage supplies keyboard and mouse input. It is a control which 
accepts focus.

The Player is a potentially complex object. In the original design,
there were to be several different types of animated objects. But as
development proceeded, it became evident that all of them were really
just the same object with some properties predefined, and rather than
risk not allowing the combination that might be most desirable for a
particular situation, a single object was created with all the 
properties available. Don't be frightened by its complexity; if one is
created and a picture assigned, then it will show the picture and not
do anything else. If sprite animation is required, the target 
coordinates are set and moving is enabled. If cell animation is needed,
it gets a bit more complicated as described below.

A bitmap assigned to a Player is assumed to be a single picture by
default. However, if cell animation is required, the fastest and most
efficient way to "package" all the frames is to put them in a single
bitmap that is larger than a single frame. The cells are organized in
a grid, much like a spreadsheet (only no lines!). On a row, from left
to right, are images which should be shown in a logical sequence. If
there are multiple logical sequences, then the other sequences are on
other rows. For instance, let's say you have a player that is 48 pels
high and 24 pels wide. On the first row you might have him face to the
right, one picture with his feet together, one with them spread apart.
On the second row you might have him do the same, only facing left. To
do this, you create a bitmap that is 96 pels wide and 48 pels wide and
draw (or paste - I suggest that somewhere you keep the images unique,
but it's up to you, of course) the first row in the upper half and the
second row in the second half. Then when this bitmap is assigned to a
Player control, set XFrames and YFrames each to 2. Set Cycle to True
(I know, I am getting ahead) and he runs in place. But set a target
location off to the right, and off he goes. Set the FrameRow to 1 and
a target off to the left and he walks that way. The example will help
to clear this up a bit.

Events for mouse clicks are generated if Player objects are clicked on.
There are additional events that can be generated when a Player object
arrives at a target location, runs into another Player object or 
completes a cycle of cell animation (has shown all the frames on a row).
These events must be solicited; by default they are not reported, so 
that Player objects like a flickering fire will have minimal impact on
performance.

An important concept to remember is that every object on the Stage is a
Player, but that does not mean that you have to move them all with
keystrokes. Not at all. Generally speaking, one Player will be your
"hero" or "heroine" and the others will be props, hazards, bullets or
bad guys.

Another important thing to note: There is a lot that can be done with
animation besides game programming, such as sprucing up a logo display
in the about box or even simulating screens for training.

Planned enhancements will allow 3D scenes to be created, easing the
creation of games such as adventures or golf where the player (or ball)
moves in a room or landscape. If sound is a common request, it may be
implemented, though the multimedia controls should work with ANIMATE
without any problem. Perhaps sound might be desirable using the old
voice functions for lesser/older machines. Suggestions are welcome.

Now for some "legalese":

CANIMATE is a licensed product of Componere Software. The version
included is an evaluation version and may be used to develop for
any length of time you wish; however, you cannot ship it with a
product, even if that that product is free. 

The evaluation version may be freely redistributed as long as all
the files accompany it, and it is not distributed as part of another
product. A note to BBS operators: A window will appear in the background
indicating that this is an unregistered version. This is to be expected
and it is an indication that it is in fact the evaluation version. There
is tamper detection logic included which requires that the evaluation
copyright window not be disabled.

You may purchase a registered version from:

Componere Software
1381 Kildaire Farm Rd #119
Cary, NC, 27511-5525

There are two prices for CANIMATE.VBX. If you want to redistribute 
applications which use the animation provided, it is $39 (US dollars
only) for unlimited redistribution rights of the runtime version, 
plus a single use license for the development version. If you only
want the development version for personal use, with no redistribution
rights, you can order it for $19. The advantage of the development
version over the provided demo version is that you will be notified
of updates, given support and you will be able to sleep at night :)

An order form is included in ORDER.TXT. Please use it to order.

If you have any questions, contact:
EMail: Componere@aol.com


Trouble shooting is listed before the explanation of properties
just to raise your level of awareness that the section exists.
There are some concepts in this VBX which may not be immediately
obvious, most notably having to set a property to get motion or
cycling to begin, and receiving events for collisions, arrivals
and cycles.


********************
* TROUBLE SHOOTING *
********************
Common Problems
---------------

(stuff I even forget myself :)

IF NOTHING MOVES OR CYCLES THROUGH FRAMES:
Don't forget to set the Interval values for Stage and Player!!!!
Don't forget to set the Interval values for Stage and Player!!!!
If it is zeroed, I assume that you want to freeze frame; in fact,
that is the best way to implement a pause in your game.

IF A PLAYER DOESN'T MOVE OR STOPS MOVING:
To get a player to move, set TargetX, TargetY and set Moving to True.
When the player arrives at the target, it will stop and Moving will be
set to False; you have to retarget and set Moving true again to get
more movement.

IF A PLAYER NEVER CYCLES THROUGH FRAMES:
Cycling must be set to True to use cell animation. Cycling will
remain True after a Cycle event (unlike Moving) unless you turn
it off.

IF YOU AREN'T GETTING ANY EVENTS FOR A PLAYER:
You must set the flag for the events you want (CycleEvents,
CollideEvents, TargetEvents) or you will not get any events.
One of the ways the speed is maintained is by not calling the
VB handler unless it is requested. Also, see the top tip
again - Interval must be non zero!!

IF YOU AREN'T GETTING COLLISION EVENTS FOR A PLAYER:
The CollideEvent must be True and the CollideID of the Player
objects which it runs into must not be zero.

IF COLORS GET CONFUSED WHEN MULTIPLE BITMAPS ARE UP:
All the bitmaps must share the same pallette. If you use the
Windows Paintbrush program, they will all use the system
pallette.

IF MOVEMENT IS "ODD":
Make sure that your values for the grid are right, and that
the frames are evenly spread. Check the movement amounts and
remember that they must be in twips. Make sure you don't do
too much processing at cycle events.

IF COLORS SEEM TO MIX WHILE MOVING:
Some colors are composite colors; if you zoom in on them in
paint, you will see alternating bits of different colors which
appear as a single color when zoomed out. If you pick one of
these as your TransparentColor, then these bits of color will
allow the background to come through. You need to make sure 
that the color you pick to be transparent is not used at all
in the foreground of the picture; not even "mixed" in another
color. A tip - you can get some interesting effects by doing
this on purpose, for ghosting or flames.

EVENTS DON'T COME IN IF A MESSAGE BOX IS UP:
That's the way VB works. Events are thrown away when a message
box comes up until it goes away. You should set the Stage Interval
to zero while it is up to freeze animation, unless missing events
is unimportant.

ANIMATION STOPS WHILE DEBUGGING:
Only while in break mode. This is on purpose. You would find it
impossible to debug if events continued to happen (they get 
ignored by VB) while in break. This also allows you to examine
the "state of the world" during break at your own pace. Each
time you Go, it runs full speed.

*********************************
*Controls, properties and events*
*********************************

Stage

  Standard Properties:

    BackColor
    BorderStyle
    Height
    Index
    Left
    Name
    Tag
    Top
    Visible
    Width

  Special Properties:

    Interval  - This is the number of milliseconds to set timer events 
                for animating objects. Also see interval for Player
                control. Interval for the Stage control determines the
                granularity at which Players can be animated.

    Picture   - An optional bitmap. A stage may either use a bitmap or
                background color.

  Events:

    Sub Stage1_Click ()
      Standard mouse click event

    Sub Stage1_KeyDown (WP As Integer)
      A key was pressed.
      A WM_KEYDOWN message was received. WP is the wParam or virtual
      key code.

    Sub Stage1_KeyUp (WP As Integer)
      A key was released.
      A WM_KEYUP message was received. WP is the wParam or virtual
      key code.

    Sub Stage1_KeyChar (WP As Integer)
      A keystroke was translated into a character.
      A WM_CHAR message was received. WP is the character as an int.

Player

  Standard Properties:

    Height
    Index
    Left
    Name
    Tag
    Top
    Visible
    Width
            NOTE: Height and Width are a little different with a Player 
                  than with most other controls. Frames are not
                  stretched to fill a larger rectangle; the extra space
                  is ignored. If the space is too small, it will not 
                  clip the frame being displayed, nor shrink it. So the 
                  size of a Frame (or Picture if XFrames and YFrames
                  are both 1 or less) really determines control size.
                  IMPORTANT: All position and size properties are in twips.
                  ScaleMode doesn't work since Players are inside of the
                  Stage object, and there doesn't seem to be any clean
                  workaround.
                  
  Special Properties:

    CollideEvents    - If set to True, events will be generated if the
                       Player collides with another visible Player
                       control which has a non zero CollideID.

    CollideID        - This is used to identify the Player or type of
                       Player in a collision. It does not have to be
                       unique. For instance, you might set all hazards
                       to 1 and walls to 2 in a game. Then if you get
                       a collide event with a 1, you can "kill" your
                       player, while simply stopping for a 2.

    CycleEvents      - If set to True, events will be generated each 
                       time all the frames on a row have been shown.

    Cycling          - If True, the Player will cycle through frames
                       on a row. This enables cell animation.

    Frame            - This is a number from 0 to XFrames-1 which
                       indicates the frame currently being displayed.

    FrameRow         - This is a number from 0 to YFrames-1 which
                       indicates which row of frames are currently
                       being displayed.

    Interval         - This indicates how often the Player should be
                       updated. Each time an update occurs, the Player
                       will be moved if it is moving toward a target
                       and/or have the next frame shown if cell 
                       animation is being used. This is a multiplier
                       for the Stage's Interval. If the Interval of
                       the Stage is set to 111 and the Interval of
                       the Player is set to 3, it will be updated
                       every 333 milliseconds (approx) or about 3
                       times a second, for example.

    Moving           - If set to True, the Player will begin moving 
                       toward the target location if/when it is
                       different than the current location.

    Picture          - The bitmap. If XFrames and YFrames are 1 or 0, 
                       then it is simply a single picture. Otherwise,
                       it is a collection of frames all of equal size
                       arranged in a grid.

    TargetEvents     - If set to True, events will be generated when the
                       Player reaches a target location.

    TargetX          - The target location X coordinate in twips.

    TargetY          - The target location Y coordinate in twips.

    TransparentColor - The color in the bitmap which should not paint 
                       over objects or background beneath. Also, a
                       collision does not occur if either of the
                       overlapping areas is completely transparent.

    Text             - A character string to write into the control.

    TextColor        - The color to use for text

    XFrames          - The number of frames on each row if > 1.

    XMoveAmount      - The maximum number of twips to move on each
                       update in the X direction when moving toward a
                       target. The Player may move less in some cases
                       as dictated by slope of the line of travel or
                       proximity to the target location.

    YFrames          - The number of rows of frames in the bitmap if > 1

    YMoveAmount      - The maximum number of twips to move on each
                       update in the Y direction when moving toward a
                       target. The Player may move less in some cases
                       as dictated by slope of the line of travel or
                       proximity to the target location.

    ZPosition        - Determines paint order; the lower the number
                       the later it is painted (0 = topmost). If this
                       is not set, the order will be the order in which
                       the controls are created. Collisions may still
                       be reported even if ZOrders are not equal. You
                       might choose to set the ZOrder of some Player
                       control, like a bush, lower than a Player that
                       is your "hero" so that the hero can hide behind
                       the bush (some hero :)

  Events:

    Sub Player1_AtTarget ()
      The player was in motion and has arrived at the target location.
      TargetEvents must be True for this event to be generated.

    Sub Player1_Click ()
      The standard mouse click event.
      
    Sub Player1_Collide (ID As Integer)
      The Player is in motion and has collided with another Player
      control which has a non zero CollideID. The ID is the CollideID of
      the other Player control. 
      CollideEvents must be True for this event to be generated.

    Sub Player1_Cycle ()
      The Player is cycling through frame animation and has completed a
      cycle (shown all the images on a frame row). If nothing is done to
      change the state, the Player will continue cycling, starting at 
      Frame 0 on the current FrameRow.
      CycleEvents must be True for this event to be generated.

