Ev9 Docs (eMotions Presentation Foundation)

The eMotions Render Engine

The eMotions Render Engine is a high-speed 2D graphics rendering engine designed with PowerBASIC and WindowsAPI. eMotions uses Windows 32 API because it is lightweight, portable and more stable across many different video cards. This documentation will provide a detailed explanation of eMotions script syntax and APIs.

How eMotions Works

The eMotions Engine uses a simple command for its .MOTION files. These files are created similar to an .ini file. The parameter values within this .ini file are used to create and control graphics objects within eMotions. These "objects" can be game sprites, pictures, interface buttons and even text. eMotions makes it possible to move, rotate, and animate objects within a simple "open" text file syntax.

eMotions objects are created and controlled by a unique name. (i.e. {spritename}) The eMotions object BLOCK refers to the BEGIN: and END: tag used for setting a sprite object properties.

The eMotions (demo) is 90% functional and only allows eMotions to operate via the script interpreter. Registered users will have full access to the script interpreter, eMotions APIs as well as the event processor.

The eMotions Script Syntax

When the eMotions engine is executed, it immediately reads for the "engine.ini". The engine.ini contains the script commands that explain how eMotions will operate. eMotions can render within a window, directly to the screen (desktop), as a background process and to a bitmap file as a screen capture. Below is a sample of the engine.ini file that is included with eMotions followed by an explanation of each script command.

OUTPUT = WINDOW
OUTPUTSIZE = VIEWPORT
GAMETITLE = eMotions Render Engine v1.00.00
RESAMPLE = 1.0
VIEWPORTCOLOR = &H202020
VIEWPORTPOS = (SCREEN_WIDTH% / 2) - (DLG_WIDTH% / 2), (SCREEN_HEIGHT% / 2) - (DLG_HEIGHT% / 2)
VIEWPORTSIZE = 800, 600
VIEWPORTTYPE = 2
SHOWBARRIERS = TRUE
MINIMUMVRAM = 32
MAXIMIZE = FALSE
ENABLEQUE = TRUE
ENABLEPROCESSOR = TRUE
ENABLELIGHTING = TRUE, FALSE
FONT = Tahoma
DEBUG = FALSE

*New!*
ALWAYSONTOP = TRUE
LOCKCURSOR = FALSE

Initialization Script Commands

INCLUDE = {motion file}

The INCLUDE command allows you to embed eMOTION script files within each other. Reusable script sequences can be saved as seperate external .MOTION files and INCLUDED when they are needed. INCLUDED files can use macro embedded variables ( i.e. #variable# ) to allow for dynamic scripts.

OUTPUT = {WINDOW, SCREEN, BACKGROUND, FILE}

The OUTPUT command tells eMotions what to do when it is executed. Setting this property to WINDOW will create a Graphics Window of a given size that eMotions will render graphics. Using the SCREEN setting will instruct eMotions to draw directly on the desktop. The BACKGROUND property will create the render screen in memory and eMotions will run purely as a background process. You can access the destination render within your own application using the eMotions APIs. The FILE parameter will allow you to specify a filename to render as a screen capture. The OUTPUT script command is only valid within the engine.ini file.

OUTPUTSIZE = {VIEWPORT | W, H}

The OUTPUT command tells eMotions the size of the render output. Using the keyword VIEWPORT will set the render size equal to the current eMotions window size. Specifying a Width and Height will allow a smaller or larger render size to be used. Using a different render size than the viewport can affect performance.

UNLOAD = {spritename1, spritename2, ....}

The UNLOAD command will completely remove an eMotion sprite from memory. It will attempt to remove any graphics, and animations the sprite was using ONLY if the graphics are currently in use by another sprite. If in use, the graphic will unload when the last sprite using the graphics is UNLOADED.

HIDE = {spritename1, spritename2, ....}

The HIDE command will set all sprites listed to VISIBLE = FALSE. (See the VISIBLE parameter for more details.)

DEBUG = {T/F}

SHOW = {spritename1, spritename2, ....}

The SHOW command will set all sprites listed to VISIBLE = TRUE. (See the VISIBLE parameter for more details.)

QUIT

The QUIT command will completely exit the eMotions engine. All sprites are UNLOADED, the desktop is restored, and memory released back to the Operating System.

INVISIBLE =

The INVISIBLE command will set all sprites listed to BLT = INVISIBLE. Changing the BLT to INVISIBLE will mean the sprite is 100% functional, but is simply not viewable on the screen. The sprite will collide, with other sprites and respond to mouse clicks as well as trigger event scripts. (See the VISIBLE parameter for more details.)

PATH = {relative path}

The PATH command will allows you to set the global path for all script commands that execute within your .MOTION script file. Setting this command at the beginning of the MOTION file means you no longer have to specify a complete DRIVE:\PATH location when referencing scripts or image files.

MINIMUMRAM = {minimum System RAM in MB}

The MINIMUMRAM command informs the eMotions engine of the minimum amount of system ram required to run your application. If the system has less than this minimum setting, eMotions will display a system message and shut down.

MINIMUMCOLOR = {minimum Color Depth (16 or 32) bits}

The MINIMUMCOLOR command informs the eMotions engine of the minimum system color depth required to run your application. If the system desktop display is less than this color setting, eMotions will display a system message and shut down.

MINIMUMRESOLUTION = {minimum Screen Resolution in pixels}

The MINIMUMRESOLUTION command informs the eMotions engine of the minimum desktop size required to run your application. If the system desktop size is less than this minimum resolution, eMotions will display a system message and shut down.

MINIMUMVRAM = {minimum Video RAM in MB}

The MINIMUMVRAM command instructs eMotions the minimum amount of Video RAM required to run your application. eMotions will check the systems minimum video specs. If the system video ram is less than this setting eMotions will inform the user and exit.

MAXIMIZE = {True/False}

The MAXIMIZE command works in WINDOW mode and instructs eMotions to maximize the render surface to the entire size of the screen.

ENABLEREDRAW = {True/False}

The ENABLEREDRAW command will control whether the eMotions engine will display the render on the active viewport. All sprite motion, collision, and script triggers will operate as normal but will simply not be drawn to the screen.

ENABLEQUE = {True/False}

The ENABLEQUE command will activate the eMotions script-processing queue. eMotions will check the \EXE folder for .MOTION files and immediately execute them. As each script is executed, eMotions will delete the file until the \EXE folder is empty.

ENABLEPROCESSOR = {True/False}

The ENABLEPROCESSOR command will activate the eMotions event message queue. This queue will trap mouse and engine events and can be access from outside programs via the eMotions APIs.

ENABLELIGHTING = {True/False , True/False}

The ENABLELIGHTING command will enable the embedded 2D overhead light source features. The first parameter enables lighting the second enables high quality lighting.

FONT = {fontname}

The FONT command specifies the default FONT eMotions will use when text is displayed. eMotions has the following embedded FONT templates. A font-template is a simple bitmap surface containing a complete alphanumeric text character set. eMotions supports the following fonts.

ARIAL
SANSSMALL
BARD
TERMINALSMALL
COURIERNEW
VERDANASMALL
CALLIGRAPHY
SMALLFONT
GEORGIA
TAHOMA
VERDANA

GAMETITLE = {your text here}

The GAMETITLE command allows you to specify the title caption when eMotions operates in WINDOW mode.

RESAMPLE = {0.0 to 3.0}

The RESAMPLE commands allows you to auto resize all graphics at the time that are loaded and initialized within the engine. Re-sampling graphics will save memory while showing only a minor decrease in graphic quality.

VIEWPORTCOLOR = {hex color}

The VIEWPORTCOLOR command specifies the actual background of the render surface. Generally the background is BLACK or a DARK GREY.

VIEWPORTPOS = {x,y} (in pixels)

The VIEWPORTPOS command specifies the upper left corner of the render surface when eMotions is running in WINDOW or SCREEN mode.

VIEWPORTSIZE = {width, height} (in pixels)

The VIEWPORTSIZE command allows you to specify the size of the render surface. This command is only valid within the engine.ini

VIEWPORTTYPE = {#}

The VIEWPORTTYPE command allows you to control how a view-port will behave. This command will set if a view-port will deflect objects when they reach the edge of the view-port or wrap to the opposite side of the view-port. This script commands has three settings.

0 = VIEWPORT : The render surface is a view-port with a relative position to a larger world surface. The render
surface is simply a view window.

1 = WRAPPING : The render surface will automatically wrap sprites and objects around when they collide
with its edge.

2 = BLOCKING : The render surface will act as container for all sprites and objects. Objects & Sprites will stop
moving or be deflected when they collide with the edit of the render surface.

LOCKCURSOR = {True/False}

SHOWBARRIERS = {True/False}

The SHOWBARRIERS command will instruct eMotions to Hide or Show any barrier lines created within the surface area.

SETBARRIER = {x1,y1,x2,y2} : Draws a Barrier Line On Map from (x1,y1) - (x2,y2)

The SETBARRIER command will create a barrier line on the render surface. The coordinates for this barrier must be within the range of your VIEWPORTSIZE. The barrier lines can be shown or hidden with the SHOWBARRIERS command. If the SETBARRIER command is used within an object block (see eMotions Graphics Object below), the object created will be a PARENT of the barrier line. If the object is moved, the barrier line will also move with the object.

eMotions Timer Controls

eMotions operates as a real-time rendering engine, which allows you to design your .MOTION scripts to operate over a span of time. (Given in Seconds). eMotions processes time event scripts in sequence, which allows users to trigger external scripts as needed.

CLEAR = TRUE

The CLEAR command will clear all graphics, sprites, viewports, and barriers. This command will reset the entire eMotions display and prepare it for new sprites to be loaded.

CLEARTIMER = TRUE : Resets the TIMER counter to 0

The CLEARTIMER command will reset the eMotions TIMER counter to 0. The eMotions timer will loop automatically, but at any time you require the counter to reset you can simply clear it.

CLEARTIMEDEVENTS = TRUE : Clears All Timed Events in Queue

The CLEARTIMEDEVENTS command will remove all .MOTION scripts you have set to trigger at a given time.

ENABLETIMER = {T/F}, {T/F}, {RANGE} : Enables & Clears Script Timer, Sets Looping,

& Timer Range

The ENABLETIMER command will activate/de-activate the eMotions timer. The first parameter will enable the timer, the second instructs eMotions to CLEAR all previous events, and the final parameter will set the range of the event. The following command will activate the eMotions TIMER and set the operating interval to 120 seconds. It will not clear the TIMEREVENTS, so any previous events will trigger on the second they are specified.

ENABLETIMER = True, False, 120

SETTIMER = {00} : Sets the TIMER counter to a value (0 - {RANGE})

The SETTIMER command will set the value of the TIMER counter. This allows you to skip TIME EVENT TRIGGERs if necessary.

SETTIME = 24:00

DAY = 1

YEAR = 1900

TIMEDEVENT = {00}, {FILE} : Sets the Time in seconds and .motion file

to execute

The TIMEDEVENT command will bind an external .MOTION file to trigger at a given second within your Timer Interval. The file path is relative to the eMotions engine. (see the PATH command)

eMotions Graphics Objects

The eMotions Engine support four different graphics types. These graphics types can be used individually or as groups to create a wide variety of graphic effects. The following will explain the core syntax for creating eMotions Graphics Objects.

BEGIN: OBJECTNAME

UNLOAD = {T/F}
PRIVATE = {T/F}
TYPE = {TYPE}                            : PROP, SPRITE, PLANE, TEXT, LAYER
PARENT = {spritename, T/F}               : Sets a PARENT for this sprite
INDEX = {lo, hi}                         : Sprite Index From low value to high value
LISTINDEX = {val}
POS = {X,Y}                              : LEFT, TOP LOCATION IN PIXELS
POS3D = {X,Y,Z}                          : X, Y, Z LOCATION IN PIXELS
POSTO = {X,Y}                            : LEFT, TOP DESTINATION LOCATION IN PIXELS
POSTO3D = {X,Y,Z}                          : X, Y, Z DESTINATION LOCATION IN PIXELS
ROT = {Ang}                              : Set the Rotation Angle for Sprite in degrees 0.0 - 360.0
POSTO = {xAng, yAng, zAng}               : X, Y, Z AXIS Angles in Degrees
SIZE = {W,H}                             : WIDTH, HEIGHT IN PIXELS
CENTERSIZE = {x1, y1}                    : Changes Size of Object but keeps CENTER position
BLT = {BLTMETHOD}                        : HOW TO DISPLAY? COPY, TRANSPARENT, DITHER##, ALPHABLEND##
ALPHA = {0.000 - 1.000}                  : Custom Alphablend Percentage
FRICTION = {~Value}                      : Custom Speed Adjustment Co-efficient
DITHER = {}
LAYER = {00}                             : Sets the Redraw Layer for sprite (ZOrder)
TAG = MyObject                           : Sets a CUSTOM TEXT field within the Object
VIEWPORT = {x1,y1,x2,y2}                 :
SETBARRIER = {x1,y1,x2,y2}               : Draws a Barrier Line On Map from (x1,y1) - (x2,y2)
LIGHTING = {TYPE},{LA,HA},{W,H}         : Lighting Arc(LO & HI) (Width & Height of LightSource 4, 8, 12, 16, 20, 24, 28, 32)

LIGHTHUE = {R,G,B,A}                     : Adjust the color of the light source
CASTSHADOW = (T/F,W,H}                   : Object will cast a shadow a length between W and H depending on cast direction.)

CAPTION = {TEXT$}                        : Sets the Caption for TEXT Sprites
CANEDIT = {T/F}
CANDRAG = {T/F}, {T/F}
TEXTWRAP = {T/F},{T/F}                   : Sets WordWrap & Vertical Enlarge Property for TEXT Sprites
TEXTPOS = {x,y}                          : Sets the upper left position for Caption Text.
FONT = {FONTNAME}                        : Sets the Current Game Font palette
FONTCOLOR = {&HFFFFFF}                   : Sets Font Color
PASSWORD =

IMAGE = {FILENAME}                       : Filename of Sprite
RESIZE = {T/F}, {T/F}                    : Will Sprite Resize with Form
COLLISION = {T/F},{T/F}                  : Will Sprite Collide with Other Sprites & Deflect
WALLCOLLISION = {T/F},{T/F}              : Will Sprite Collide with Walls & Deflect
ENABLED = {T/F}                          : Is Sprite Enabled
EVENTS = {T/F}, {FILE}                   : Does Sprite trigger Mouse Events? Set scriptfile?
LISTMODE =
{V,H}LIST =                              : Specify As List of data.

FRAMES = {hF, vF, #F, AnmI}              : {horizFrames, vertFrames, #AnimFrames, Anim Interval}
INSTANCE = {Row, Col}                    : SET Sprite TO Specific FRAME by Row, Column
ANIM = {Frame, Dir}                      : Set Sprite to Specific Frame by Anim & Direction
ARC = {Peak, Dur}                        : SET Arc Peak & Duration FOR special POSCHANGE FUNCTION
ALPHACHANGE = {~ALPHA,Dur}               : Change the AlphaBlend Value Over a Duration
DITHERCHANGE = {}                        : N/A

POSCHANGE = {~X,~Y,*Func,Dur}            : Position Change X,Y,Func,Duration
POSCHANGE3D = {~X,~Y,~Z,*Func,Dur}      : Position Change X,Y,Z,Func,Duration
SIZECHANGE = {~W,~H,*Func,Dur}          : Size Change Width, Height, Func, Duration
ROTCHANGE = {~Ang,*Func,Dur}             : Rotation Change Angle, Duration (Z-Axis)
ROTZCHANGE = {~Ang,*Func,Dur}            : Rotation Change Angle, Duration (Z-Axis)
ROTXCHANGE = {~Ang,*Func,Dur}            : Rotation Change Angle, Duration (X-Axis)
ROTYCHANGE = {~Ang,*Func,Dur}            : Rotation Change Angle, Duration (Y-Axis)

END: BACKGROUND

The above commands enabled eMotions to create dynamic objects, user interface controls, games and even animated screen savers, all using an open-source scripting language. The script language allows inline math functions, and a powerful command syntax to allow a real-time engine to be control by mere un-compiled text.

eMotions Object Functions

GETSPRITE {spritename}

API :

The GETSPRITE command will load a current sprite data into eMotions script variables. All eMotions Sprite properties are stored in variables with the EMT_ prefix. If the sprite is ATTACHED or has a PARENT the parent of the sprite is automatically called loaded in the PARENT_ variables. These variables may be then analyzed or compared within script events. Performing this command is considered setting a sprite into FOCUS.

LOADSPRITE {spritename, custom}

API :

The LOADSPRITE command will load a current sprite data into eMotions script variables. All eMotions Sprite properties are stored in variables with the custom_ prefix name. This command will NOT load any of the sprites parent data. These variables may be then analyzed or compared within script events. Performing this command will not affect the current sprite in FOCUS. This command is used to help when loading, editing and comparing multiple sprites simultaneously.

NOTE: After you have completed using this sprite, you MUST MANUALLY clear all of the sprite variables. Failing to clean up this data can result in out of memory errors. You may used the DelVars {custom} command to delete all variables with the custom_ prefix.

SETPROPERTY {spritename, property, variable}

API : SUB pbSetProperty (bmpNME AS STRING, propName AS STRING, newVal AS STRING)

The SETPROPERTY command will allow you to set the property of any sprite to a value constant, or a value stored within a system variable. The SETPROPERTY command works without selecting the sprite into FOCUS, so it does not interfere with the LOADSPRITE{} command. This command may be used to avoid using repeated BEGIN: & END: object blocks within your script. You may however, overwrite the spritename property with a FOCUSED sprite variable by using any of the EMT_ or PARENT_ variables. (See LOADSPRITE{} command.)

GETPROPERTY {spritename, property, variable}

API : SUB pbGetProperty (bmpNME AS STRING, propName AS STRING, destVariableName AS STRING)

API : FUNCTION GetProperty (bmpNME AS STRING, propName AS STRING) AS STRING

The GETPROPERTY command will allow you to retrieve a property of any sprite into a system variable. The GETPROPERTY command works without setting the sprite into FOCUS, so it does not interfere with the LOADSPRITE{} command. This command may be used to avoid using repeated BEGIN: & END: object blocks within your script. You may however, overwrite a FOCUSED sprite variable with this command by using any of the EMT_ or PARENT_ variables as the destination variable. (See LOADSPRITE{} command.)

TRIGGER {event,spritename}

API :

The TRIGGER command will enable you to TRIGGER a script event within an external eMotions sprite. The unique spritename must be provided as well as the script event you would like to execute. (See eMotions Event Triggers for more information.)

IF{}
ENDIF:{}

SELECT {}
    CASE:{= }
    CASE:{= }
    CASE:{= }
ENDCASE {}

MSGBOX {}

PLAY{}
PLAY!{filepath, handle, x, y, w, h}

The PLAY command will play any of the standard windows sound and multimedia files. Sound files will ignore the {x,y, w, h} parameter. Video files will use these parameters to open a play back window for the video to be displayed.

LOG {}

Standard Variables & Calculation Functions

SetVal {variable, value}
SetVar {variable, value}

API : SUB SetVal(BYREF variableName$, BYREF variableValue$)

DelVal {variable}
DelVar {variable}

API : SUB DelVar(BYREF variableName$)

DelValsLike {variable prefix}
DelVarsLike {variable prefix}

API : SUB DelVarsLike (variableName$) EXPORT

DelValsWith {variable characters}
DelVarsWith {variable characters}

API : SUB DelVarsContaining (variableName$)

Retreiving eMotions Variable Data with Code.

API : FUNCTION GetIntVal (lname$) AS LONG
API : FUNCTION GetDecVal (lname$) AS SINGLE
API : FUNCTION GetStrVal (lname$) AS STRING

To retrieve values from variables during script execution time, eMotions uses two methods of inline variable translation. Simply embedding the variable with the number sign (#NAME$#) character, will insert the value of any system variable as the start of script execution. By using brackets [NAME$] around any variable, the parser will wait until that line is executed before embedding the value. (This will allow for variables to be calculated within the script just prior to being embedded for use.)

Three unique characters note eMotions script variables. ($, %, !) Any variable name must have one of those following characters at the end of it to be recognized as a variable.

MYVAR$ : MYVAR is a Long Integer variable between the ranges of -2,147,483,648 to +2,147,483,647. Long Integers can not contain decimal points.

MYVAR! : MYVAR is a Single Point variable between the ranges of +/- 8.43x10^-37 to 3.40x10^38.

MYVAR$ : MYVAR is a String Variable of 160 characters max.

To set & calculate variables, eMotions uses two unique commands. SetVal {} and Calc{}. eMotions supports full inline equations parsing which allows complex math functions to be performed with ease.

SetVal {MYPI!, 22 / 7}

or

Calc {MYPI! = 22 / 7}

Each of these functions will store 3.1457... into the MYPI! Single Point variable. This variable can be used at any time within an eMotions Object Block. eMotions also maintains several standard variables for use within your application. These variables hold information such as the desktop screen size, and many system settings that are determined during eMotion's initialization.

Standard Object Parameters

BEGIN: MY OBJECT

TYPE = {TYPE} : PROP, SPRITE, PLANE, TEXT, LAYER
PARENT = {spritename} : Sets a PARENT for this sprite
INDEX = {lo, hi} : Array of Objects Indexes From low value to high value

IMAGE = {FILENAME} : Filename of Sprite
POS = {X,Y} : LEFT, TOP LOCATION IN PIXELS
ROT = {Ang} : Set the Rotation Angle for Sprite in degrees 0.0 - 360.0

SIZE = {W,H} : WIDTH, HEIGHT IN PIXELS
RESIZE = {T/F} : Will Sprite Resize when the Form changes size

BLT = {BLTMETHOD} : HOW TO DISPLAY? COPY, TRANSPARENT, DITHER##, ALPHABLEND##
ALPHA = {0.000 - 1.000} : Custom Alphablend Percentage
BORDER = {T/F}, {00} : Object will have a skinable border.
LAYER = {00} : Sets the Redraw Layer for sprite (ZOrder)

ENABLED = {T/F} : Is Sprite Enabled

END: MY OBJECT

The above parameters are the standard properties for any eMotions graphics object. The BEGIN: {spritename} and END: {spritename} tags denote an eMotions object. The parameters can be set in any order, between the BEGIN/END tags. The bold parameters are mandatory for eMotions to create the object, all other parameters are optional or used for specific effects. This documentation will provide some insight on producing eMotions graphic objects, as well as some practical examples of how these objects could have been used in historical games.

SNAP {vT/F, hT/F}

API : None

The SNAP command will snap a sprite to the nearest horizontal or vertical viewport edge. This command will not stack sprites or account for sprites already snapped to a given edge.

FRICTION = {#}

API : SUB SetSpriteFRICTION (bmpNME AS STRING, BYVAL bmpFRICTION AS SINGLE)

The FRICTION command.

VIEWPORT = {Left, Top, Right, Bottom}

API : FUNCTION SetViewPort (bmpNME AS STRING,

BYVAL vTYP AS INTEGER,

BYVAL vLFT AS LONG,

BYVAL vTOP AS LONG,

BYVAL vRGT AS LONG,

BYVAL vBOT AS LONG ) AS LONG

The VIEWPORT command.

CANDRAG {hT/F}, {vT/F}

API : FUNCTION SetSpriteDRAG ( bmpNME AS STRING,

BYVAL CanHDrag AS INTEGER,

BYVAL CanVDrag AS INTEGER,

BYVAL CntrDrag AS INTEGER) AS LONG

The CANDRAG parameter explains to eMotions if the object can be drag/dropped around the screen by the mouse pointer. The eMotions sprite can be set to allow horizonal and/or vertical dragging. Enabling both horizontal and vertical dragging allows a sprite to be freely moved anywhere within the viewport.

TYPE = {PROP, SPRITE, PLANE, TEXT, LAYER}

API : SUB CreateSprite (bmpNME AS STRING,

BYVAL bmpType AS LONG,

BYVAL bmpW AS LONG,

BYVAL bmpH AS LONG)

SUB CreateSpriteFULL (bmpNME AS STRING,

BYVAL bmpType AS LONG,

BYVAL bmpL AS LONG,

BYVAL bmpT AS LONG,

BYVAL bmpZ AS LONG,

BYVAL bmpW AS LONG,

BYVAL bmpH AS LONG,

BYVAL bmpBLT AS LONG)

The TYPE parameter explains to eMotions the type of graphics object you are creating. Each graphics type has different feature/functions and behave differently within eMotions. Depending on the type, the object will have access to different parameters. Only TEXT objects have access to the TEXT parameters. (see Text Parameters below.) Only SPRITE objects have access to the Animation parameters. (see Animation Parameters)

An eMotions PROP is a single frame graphics object. The eMotions SPRITE property will create a multi-framed animated object. An eMotions TEXT object will display font rendered characters and accept TEXT input. The LAYER object is a single frame floating graphic that exists independent of the VIEWPORT. The PLANE object is a PROP used to create a world map which the VIEWPORT is embedded.

IMAGE = {FILENAME}

API : FUNCTION SetSpriteIMAGE (bmpNME AS STRING,

bmpFILE AS STRING,

BYVAL imgInit AS INTEGER,

BYVAL bmpResize AS INTEGER,

BYVAL dynaSize AS INTEGER,

BYVAL bmpCollide AS INTEGER,

BYVAL sDeflect AS INTEGER,

BYVAL bmpWallCollide AS INTEGER,

BYVAL sWDeflect AS INTEGER) AS LONG

The IMAGE parameter instructs eMotions of the image file that creates the graphics object. eMotions uses FreeImage .DLL support so it supports a wide variety of graphic file formats. However, certain graphic object use compression which affect how objects can be displayed. JPG files can alter the actual color values which means making transparent object can cause image bleeding or inaccuracy in the graphic display.

POS = {X,Y}

POS3D = {X,Y}

API : FUNCTION SetSpritePOS (bmpNME AS STRING,

BYVAL bmpX AS SINGLE,

BYVAL bmpy AS SINGLE,

BYVAL bmpZ AS SINGLE) AS LONG

The POS parameter will set the upper left position (in pixels) that the graphics object will be displayed on the screen. The POS3D command was added to eMotionsv2.0 to support OpenGL within a real 3D environment. POS should be considered a depricated command and should only be used for 2D motion scripts.

SIZE = {W,H}

API : FUNCTION SetSpriteSIZE (bmpNME AS STRING,

BYVAL bmpW AS LONG,

BYVAL bmpH AS LONG) AS LONG

The SIZE parameter will set the width and height (in pixels) of the graphics object when it is displayed on the screen.

BLT = {BLTMETHOD}

API : SUB SetSpriteBLT (bmpNME AS STRING, BYVAL bmpBLT AS LONG)

The BLT parameter will instruct eMotions of how the graphics object will be displayed on the screen. eMotions can copy graphics in many different ways. Below are a list of all of the BLT methods eMotions supports with a brief description.

COPY : Copy the image EXACTLY as it appears.
TRANSPARENT : Copy the image EXACTLY with BLACK represented as transparent.
DITHER## : Dither the image a standard percent before it is displayed.
ALPHABLEND## : Alphablend the image a standard percent before it is displayed.
ALPHABLEND : Alphablend the image a custom percentage before it is displayed.
standard percent = 20, 40, 50, 60, & 80 percent of original image

Note: The Alphablend feature has 5 standard percentage setting within eMotions for convenience. If you wished to used a custom setting simply use the ALPHABLEND property and provide the custom decimal value within the ALPHA parameter. For example, the script below will AlphaBlend a graphics object at 33 percent with the background, offering a semi-transparent appearance.

BLT = ALPHABLEND
ALPHA = .33

ENABLED = {T/F}

API : FUNCTION SetSpriteENABLED (bmpNME AS STRING, BYVAL bmpACT AS LONG) AS LONG

The ENABLED parameter activates the sprite. Sprites that are ENABLED can be drag/dropped and will trigger mouse and script events. Setting this value to FALSE will enable a sprite to be displayed but not respond to other sprites, collisions, or mouse clicks.

VISIBLE = {T/F}

API : FUNCTION SetSpriteVISIBLE (bmpNME AS STRING, BYVAL bmpVISBL AS LONG) AS LONG

The VISIBLE parameter determines whether a sprite can be seen. Setting this value to FALSE will mean the sprite is NOT displayed and will not respond to collisions, or mouse clicks. Scripts events may still be triggered. (see the INVISIBLE property.)

RESET = {.MOTION RESET DATA}

API : FUNCTION SetSpriteRESET (bmpNME AS STRING, bmpFILE AS STRING) AS LONG

ATTACH = {spritename}

API : FUNCTION SetSpriteATTACH (bmpNME AS STRING, BYVAL spriteIndex AS LONG) AS LONG

The ATTACH parameter allows you to attach one sprite to another. This command will only update the location of the sprite if the main sprite is moved. Changing the SIZE, ROTATION, or BLT of the main sprite will not update any attached sprites. The only limitation with the ATTACH parameter is that two objects can't form a circular ATTACH dependency, and an object can't be a ATTACHED to itself.

GUI = {T/F}

APU : SUB SetSpriteGUI (bmpNME AS STRING, BYVAL bmpGUI AS LONG)

PRIVATE = {T/F}

API : FUNCTION SetSpritePRIVATE (bmpNME AS STRING, BYVAL bmpPRIVATE AS LONG) AS LONG

PARENT = {spritename}, {private}

API : FUNCTION SetSpritePARENT (bmpNME AS STRING, BYVAL spriteIndex AS LONG) AS LONG

The PARENT parameter allows eMotions object to establish a hierarchy of ownership. All eMotions objects will move, rotate, and size with the PARENT object it is attached. The only limitation with the PARENT parameter is that two objects can't form a circular PARENT dependency, and an object can't be a PARENT to itself.

INDEX = {lo, hi}

API : FUNCTION SetSpriteINDEX (bmpNME AS STRING, BYVAL arrayIndex AS LONG) AS LONG

The INDEX parameter allows an array of graphics objects to be created with a single parameter. When the INDEX property is used, an array of graphics objects are created with the index value as a suffix to the spritename. (spritename1, spritename2, spritename3...) Once the sprites are created the are totally independent objects.

ROT = {Ang}

ROTZ = {Ang}

ROTX = {Ang}

ROTY = {Ang}

API : SUB SetSpriteROT (bmpNME AS STRING,

rotType AS STRING, "X", "Y", "Z", or "POS"

BYVAL rotVal AS SINGLE)

The ROT parameter instructs the eMotions engine of the rotation angle the object is to be displayed. All rotation values and changes are calculated and applied dynamically. eMotions rotates objects in values from 0 to 360 degrees. At any time you want to disable the rotation, simply set this value to 0.

RESIZE = {T/F}, {T/F}

API : FUNCTION SetSpriteIMAGE (bmpNME AS STRING,

bmpFILE AS STRING,

BYVAL imgInit AS INTEGER,

BYVAL bmpResize AS INTEGER,

BYVAL dynaSize AS INTEGER,

BYVAL bmpCollide AS INTEGER,

BYVAL sDeflect AS INTEGER,

BYVAL bmpWallCollide AS INTEGER,

BYVAL sWDeflect AS INTEGER) AS LONG

The RESIZE parameter informs eMotions of graphics object that will change sizes if the view-port dialog form changes size. The RESIZE property is independent of the RESAMPLE property.

LAYER = {00}

API : SUB SetSpriteLAYER (bmpNME AS STRING, BYVAL bmpLayer AS LONG)

The LAYER parameter sets the graphic objects ZOrder, or copy order. eMotions can handle a maximum of 99 layers simultaneously. Higher most layers are copied last, so they appear on top of objects set to lower layers.

BORDER = {T/F}, {00}

API : FUNCTION SetSpriteBORDER (bmpNME AS STRING,

BYVAL bmpBDR AS LONG,

BYVAL bmpSZE AS LONG) AS LONG

The BORDER parameter informs eMotions if the graphics object has a graphics border/trim. eMotions has 7 embedded graphics "skins". If the BORDER parameter is set to True, the IMAGE parameter must be set to a graphic constructed in a standard skin format. The embedded eMotions border skins are 30 x 30 pixels in size. The embedded list item skins are 18x18 pixels in size. Regardless of the size of any custom skins you may use, the size must be divisible by 3 and create 9 quadrants that can be used to form a solid border.

The following parameter settings demonstrate how to use eMotions border skins.

IMAGE = border2.res

BORDER = True, 10

The following parameter settings demonstrate how to use eMotions list item skins.

IMAGE = listitem4.res

BORDER = True, 6

Light Sources

CASTSHADOW = {T/F}, W, H

API : FUNCTION SetSpriteSHADOW (bmpNME AS STRING,

BYVAL sShadow AS INTEGER,

BYVAL sShadowW AS INTEGER,

BYVAL sShadowH AS INTEGER) AS LONG

eMotions graphics can cast dynamic shadows when this property is set to True. Any object that has the CASTSHADOW parameter set will display a shadow extending from its origin to a distance of the CASTSHADOW width & height property.

LIGHTING = {TYPE}, {LA,HA}, {W,H}

LIGHTHUE = R, G, B, A

API : SUB SetSpriteLIGHTING (bmpNME AS STRING,

BYVAL sLight AS INTEGER,

BYVAL sLightLA AS SINGLE,

BYVAL sLightHA AS SINGLE,

BYVAL sLightW AS INTEGER,

BYVAL sLightH AS INTEGER)

API : FUNCTION SetSpriteLIGHTHUE (bmpNME AS STRING,

BYVAL sLightR AS SINGLE,

BYVAL sLightG AS SINGLE,

BYVAL sLightB AS SINGLE,

BYVAL sLightA AS SINGLE) AS LONG

eMotions supports both ambient lighting masks as well as graphics objects generating point light sources. These light sources uses embedded monochrome bitmap masks to create light for a given radius.

The TYPE parameter informs eMotions of the light source type that is attached to the object. Any graphics object within eMotions can be a light source. The object will have a glowing effect that will move as the object moves. Any objects within the illuminated area that will cast a shadow if the CASTSHADOW parameter is set.

The LA and HA parameter represent the low and high ARC that the light is cast from its origin. A light source that illuminates area completely around the graphics object would have the light ARC range from 0 to 360 degrees. For example, eMotions light masks can be used to form a light source that illuminates in a cone fashion, by simply using an ARC range of 0 to 45 degrees.

The W and H parameter set the horizontal and vertical illumination distance from the light source point of origin. The distance values must be given with the range of the view-port lighting grid. The view-port lighting grid is 1/10th the size of the overall view-port. For example, a view-port of 800x600 pixels will have a light grid range of 80x60. Selecting the appropriate range of illumination should take this conversion factor into consideration.

Animation Parameters

FRAMES = {hF, vF, #F, AnmI} : {horizFrames, vertFrames, #AnimFrames, Anim Interval}

API : FUNCTION SetSpriteFRAMES (bmpNME AS STRING,

BYVAL hFrames AS INTEGER,

BYVAL vFrames AS INTEGER,

BYVAL AnimSize AS LONG,

BYVAL AnimInterval AS INTEGER) AS LONG

The FRAMES parameter is used for SPRITE graphics objects only. It specifies the number of horizontal and vertical frames within the graphic IMAGE parameter for SPRITE objects. Once these properties are set, eMotions can reference individual frame animations by using the INSTANCE or ANIM parameters. The #F property specifies the number of sequential frames within the SPRITE sheet for constitute a complete animations sequence. A SPRITE sheet should have all the animation sequences in order of direction where applicable, so they can be referenced in logical order. The ANIMI property is used to set the animation interval for the sprite animation. The animation interval is the speed at animation frames play relative to the frames per second of eMotions. Generally eMotions operates between 40 - 60 frames per second.

INSTANCE = {Row, Col} : SET Sprite TO Specific FRAME by Row, Column

API : FUNCTION SetSpriteINSTANCE (bmpNME AS STRING,

BYVAL Rows AS INTEGER,

BYVAL Cols AS INTEGER) AS LONG

The INSTANCE parameter will allow eMotions to display, a specific frame within an animation SPRITE sheet. The ROW and COL parameters specify the location of a specific horizontal and vertical frame. There value must be between 0 and the HF and VF property values set within the FRAMES parameter respectively.

ANIM = {Frame, Dir} : Set Sprite to Specific Frame by Anim & Direction

API : FUNCTION SetSpriteANIM (bmpNME AS STRING,

BYVAL AnimIndex AS INTEGER,

BYVAL AnimDir AS INTEGER,

BYVAL AnimLoop AS INTEGER) AS LONG

The ANIM parameter allows eMotions to reference SPRITE animation frames using sprite direction values identical to Explorations Sprite formats. Below is an example of a standard sprite animation sheet.

Text Parameters

When an eMotions graphics object is set to TEXT, the follow parameters are available. The following parameters use the font rendering engine to draw text within the graphics object.

CAPTION = {TEXT$} : Sets the Caption for TEXT Sprites