README.TXT
//-------------------------------------------------------------------------
// Readme.txt
//-------------------------------------------------------------------------
// Spruuids: A sample ActiveX Scripting host, which hosts VB Script.
//-------------------------------------------------------------------------
// (C) Copyright 1992-1997 by Microsoft Corporation. All rights reserved.
//
// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//-------------------------------------------------------------------------
FILES SUPPLIED
EXTERNAL HEADER FILES
ActivScp.h -- ActiveX Scripting header file, used by Game.cpp
VBSGuids.h -- Defines CLSID for VB Script, used by Game.cpp
CompMgr.h -- Component Manager interfaces, used by App.cpp, MsgLoop.cpp
PROGRAM FILES
App.cpp, App.h
-- Implements Main App window via a dialog. CApp is responsible
for creating the CMsgLoop object, and CGame object.
MsgLoop.cpp, MsgLoop.h
-- Implements .exe's message loop via IOleComponentManager. CApp
acts as a client to the ComponentManager, implementing
IOleComponent.
OleAuto.cpp, OleAuto.h
-- Small framework for creating OLE Automation objects which have
dual interfaces.
Game.cpp, Game.h
-- Orchestrates the show, responsible for creating and coordinating
CScore, CDisplay (from Spr.cpp), and CSpriteClass's. Handles
high-level game behaviors, such as starting and ending games,
the menus, and creating, loading, and managing VB Script through
ActiveX Scripting.
GameOA.cpp
-- OLE Automation implementation for "Game" object in object model.
Score.cpp, Score.h
-- Tracks score, level, # ships left.
Spr.cpp, Spr.h
-- Core "sprite" engine, implementing CDisplay, CSpriteClass, and
CSprite.
-- CDisplay implements the display surface on which the
sprites are drawn, and handles drawing the sprites, updating
their positions on timer ticks, and tracking collisions between
the sprites.
-- CSpriteClass implements a set of functionality shared between
common kinds of sprites, such as the starting image used, how
sprites of this class interact with the border, etc.
-- CSprite implements a "sprite" which basically a repository for
position, velocity, image, etc.
SprOA.cpp
-- Implements the "SpriteClass" and "Sprite" OLE Automation
interfaces for the CSpriteClass and CSprite classes,
respectively.
Guids.cpp, Guids.h
-- Simple file to get all necessary GUIDs to the linker.
Helpers.h
-- Implements some obligatory ANSI/Unicode helpers.
Main.h
-- Main include file included by everyone.
SpruuidP.Pix, SpruuidP.hh, SpruuidP.h
-- Helper files which tells the sprite engine about the graphics
found within the main sprite bitmap, Spruuids.bmp
DispIDs.h
-- Defines the DISPIDs used for events.
Spruuids.odl
-- Declares the object model for the Spruuids.exe application.
BITMAPS
Spruuids.bmp -- Contains all of the interesting images.
Ship.bmp -- Contains the image used to display the # ships left.
Plus.bmp -- Graphics used to display a "+" when not enough room
to display # ships left.
SAMPLE SPRITE.EXE INPUT FILES
Game1.txt -- Simple samples illustrating how to use some
Game2.txt primitives from the Game object model.
Game3.txt
GameFull.txt -- Complete fun-to-play game.
CLASSES IN SPRUUIDS' IMPLEMENTATION
CApp implements
IUnknown
IDispatch Using COleAuto
SpruuidsApp
IOleComponent
CGame implements
IUnknown
IDispatch Using COleAuto
Game
IActiveScriptSite
IProvideClassInfo
IProvideClassInfo2
IConnectionPointContainer
IConnectionPoint via an embedded class
CMsgLoop implements
IOleComponentManager
CScore
CDisplay
CSpriteClass implements
IUnknown
IDispatch Using COleAuto
SpriteClass
IProvideClassInfo
IProvideClassInfo2
IConnectionPointContainer
IConnectionPoint via an embedded class
CSprite
IUnknown
IDispatch Using COleAuto
Sprite
RUNNING SPRUUIDS.EXE
Command Line:
Spruuids <VB Script File>
where
<VB Script File> is the relative or full path to a VB Script
file containing the source code which Spruuids is to load and run. See
Game*.txt for samples of VB Script programs written against Spruuids.exe.
COMPILING SPRITE.EXE
Use MkTypLib.exe to compile "Spruuids.odl" into "Spruuids.h" and
"Spruuids.tlb". NOTE THAT Spruuids.tlb MUST BE GENERATED BEFORE THE .RC
FILE CAN BE COMPILED WITH RC.EXE!
Compile each of the *.cpp files.
Use RC.exe to compile the "Spruuids.rc" into "Spruuids.res", noting that
"Spruuids.tlb" must be included as a resource of type "TYPELIB",
so it must have been created first.
Link everything togther, and use RC.exe to add the .res to the .exe.
SPRUUIDS' OBJECT MODEL
Application As SpruuidsApp
R/O Properties
Application - Returns the Application object (returns itself).
Parent - Returns the Application object (returns itself).
Game - Returns the "Game" object, described below.
Methods
Quit() - Causes Spruuids to terminate.
Game As Game
R/O Properties
Application - Returns the Application object.
Parent - Returns the Application object.
ShipClass As SpriteClass - Returns the SpriteClass for the ship.
BubbleClass As SpriteClass - Returns the SpriteClass for bubbles.
AmmoClass As SpriteClass - Returns the SpriteClass for ammo.
ExtraClass As SpriteClass - Returns the SpriteClass for extra,
special effects, or general use.
R/W Properties
Caption As String - Sets the caption of the main Spruuids window.
StatusText As String - Sets the status text of Spruuids.
Width As Integer - Width, in pixels, of the display area.
Height As Integer - Height, in pixels, of the display area.
Paused As Boolean - Sets or clears the paused game.
Score As Integer - Current score. Setting this will not compute
extra ships gained. Use AddScore() to ensure this calcualtion.
Level As Integer - Current level.
ShipCount As Integer - Current number of ships left.
ScoreFirst1Up As Integer - Score at which the first extra ship is
awarded.
ScoreSecond1Up As Integer - Score at which the second extra ship
is awarded.
DScoreNext1Up As Integer - Delta score for each extra ship award
after the second.
ShipsStart As Integer - Number of ships to start game with.
Tag As Variant - General storage for the user.
Methods
StartGame() - Starts a new game, propting the user first, if a
game is already in progress.
EndGame() - Ends the current game.
RemoveAllSprites() - Destroys all sprites.
NextLevel() - Increments the Level number, updating the level
display
Refresh() - Forces the display to be refreshed.
AddScore(amt As Integer) - Adds the given amount to the score,
rounding up to zero, if necessary. Also computes to see
if an extra ship should be awarded.
StdBorderBounce(s As Sprite, brd As Integer) - Ensures that
the sprite's velocities will cause the sprite to bounce.
StdBorderWrap(s As Sprite, brd As Integer) - Move the sprite
to the other edge of the screen.
StdInitRand(s As Sprite, u As Variant) - Moves the sprite to some
random location on the display at least u pixels away from
the center. Ensures that the sprite does not start out
overlapping a sprite it would cause a Collide event with.
StdInitEdge(s As Sprite, u As Variant) - Moves the sprite to some
random location around the edge of the display. u is ignored.
Events
NewGame() - Fired when a new game is started.
NewLevel() - Fired when NextLevel is called.
NewShip() - Fired when a new ship is awarded.
Tick() - Fired every timer tick.
Collide(s1 As Sprite, s2 As Sprite, coll As Integer) - Fired when
two sprites move so they overlap. S1 is always the sprite
with the lower id (ShipClass < BubbleClass < AmmoClass <
ExtraClass). Coll is the bit-wise AND of s1.Parent.Collide
with s2.Parent.Collide. So with judicious setting of the
Collide propertis, coll is enough to tell what types of
sprites collided, and what s1 and s2 are. Bit 1 is special
and is used to indicate that a sprite should generate this
event when it hits sprites of its own class.
KeyDown(vk As Integer) - Fired when key is depressed. vk contains
the virtual key code, as defined in Windows.h.
KeyPress(ascii As Integer) - Fired when key is depressed. ascii
contains the ascii value of the key pressed.
KeyUp(vk As Integer) - Fired when key is released. vk contains
the virtual key code, as defined in Windows.h.
MouseMove(x As Integer, y As Integer, keys As Integer, button As
Integer) - Fired when mouse moves over the play surface of
Spruuids. x and y are the pixel location of the mouse relative
to the upper left corner of the play surface. keys indicates
whether the SHIFT key is depressed (bit 1) or the CONTROL key
is depressed (bit 2). button indicates which buttons are
currently depressed (any combination of: 1=left, 2=right,
4=middle).
MouseDown(x As Integer, y As Integer, keys As Integer, button As
Integer) - Fired when the user depresses a mouse button.
button indicates which button was depressed (one of: 1=left,
2=right, 4=middle).
MouseUp(x As Integer, y As Integer, keys As Integer, button As
Integer) - Fired when the user releases a mouse button.
button indicates which button was released (one of: 1=left,
2=right, 4=middle).
SpriteClass Objects
R/O Properties
Application - Returns the Application object.
Parent - Returns the Game object.
SpriteCount As Integer - The number of existing sprites of
this kind.
R/W Properties
Image As Integer - A number indicating the default graphic
to be used for sprites of this class.
Brd As Integer - A bitfield indicating the display borders with
which sprites of this class are interested in being notified
(via the Border event) when then touch them. See Spr.h for
the definition of this bitfield.
Collide As Integer - a bitfield used to determine whether to fire
the Game_Collide event, as described above.
Friction As Single - Indicates the amount of friction sprites of
this class should default to. Values 0<n<1 slow the ship. The
value 1 is the same as no friction (default). Values >1 will
cause the ship to automatically accelerate. Values <0, who
knows?
Tag As Variant - General storage for the user.
Methods
CreateSprite(Left As Integer, Top As Integer, u As Variant) As Sprite
A function which creates a new instance of a sprite of this
class, at the given location. U is passed to the Init event,
allowing the user to pass information into that event. This
function returns a reference to the sprite object created.
Events
Init(s As Sprite, u As Variant) - Fired when sprite is first
created. U is the parameter passed to CreateSprite().
Tick(s As Sprite) - Fired every s.TickEvt timer ticks.
Border(s As Sprite, brd As Border) - Fired when sprite touches
a display border indicated by the Brd property. Calling
s.IgnoreMove() during this event will cause the sprite
to return to its position it was at before the move which
caused this event.
Term(s As Sprite) - Called before sprite object is destroyed.
LastTerm() - Fired when no more sprites of this sprite class
exist.
Sprite Objects
R/O Properties
Application - Returns the Application object.
Parent - Returns the Game object.
Width As Integer - Width of sprite's graphic in pixels.
Height As Integer - Height of sprite's graphic in pixels.
R/W Properties
Left As Single - Left position in pixels (may be fractional).
Top As Single - Top position in pixels (may be fractional).
Vx As Single - Horizontal velocity in pixels per TickMove ticks
(may be fractional).
Vy As Single - Vertical velocity in pixels per TickMove ticks
(may be fractional).
Ax As Single - Horizontal acceleration in pixels per TickMove ticks
(may be fractional).
Ay As Single - Vertical accekeration in pixels per TickMove ticks
(may be fractional).
FrictionX As Single - Horizontal friction. See description of
Friction for SpriteClass (may be fractional).
FrictionY As Single - Vertical friction. See description of
Friction for SpriteClass (may be fractional).
Image As Integer - Graphic associated with this sprite. See
SpruuidP.pix and SpruuidP.hh for a list of numbers and their
graphics.
TickMove As Integer - The number of ticks between times the sprite
engine move this sprite by Vx and Vy.
TickEvt As Integer - The number of ticks between SpriteClass_Tick
events.
Visible As Boolean - Indicates whether this sprite is visible or
not. Invisible sprites never cause Collide events.
Tag As Variant - General storage for the user.
Methods
MoveTo(Left As Single, Top As Single) - Move the sprite to the
given location.
MoveBy(Left As Single, Top As Single) - Move the sprite by the
given amount.
Remove() - Destroys the sprite.
Refresh() - Forces the sprite to repaint, if it is visible.
IgnoreMove() - Called from within the Collide or Border events
to indicate that the move which caused this sprite to collide
or touch a border should not be made.
//--- EOF -----------------------------------------------------------------