--------------------------------------------------------------------
faktory demo script tutorial
1) Basics
you must use the following directory structure
/demo
/demo/data/
/demo/data/music/
/demo/data/textures/
/demo/data/scenes/
in /demo goes your .exe
in /demo/data goes script.txt
demo.exe takes 1 parameter and that is the name of the script file.
By default it will try to run /data/script.txt, but you can overwrite
that with a parameter.
demo data/script2.txt
2) Creating the demo
in the script do:
now you have a demo :)
btw - you can use a shorthand for xml also like this:
of course it is only for xml tags that don't have children, but
parameters are fine.
IT won't do anything, because you have to add effects in and tell
it what to do!
But first lets change some parameters.
The text is quite flexible so you can arrange it nicely:
/>
if you wanted too..
Then to
3) Adding Effects
You should check effects.txt for the list of effects.
New effects are added all the time. Effects can very
simple or very complicated. They could have lots of
scriptable parameters..or none.
Once the effect is added you can set any of its parameters.
4) Default effects
There are default effects that you don't have to create.
One is "draworder".
More later...
5) Events
The demo will be quite boring without effects I think :)
Events can be triggered by:
time
keypress
time:
This is in seconds from when the is started.
keypress:
When you run the demo and press "q" it will trigger those
commands.
So to generate events you can type them into the text file,
but this can take a long time - especially for syncing music
instruments like claps to flashes. So how about a way to
generate events easily?
The demo will now create a keylog.txt file when you run it,
with a list of the keys you press and what time you did it at.
Simply copy this .txt file into the script and run the demo
again and the events will trigger :) Then you can edit the
script to remove and incorrect events or to tweak them.
--------------------------------------------------------------------
faktory demo code tutorial
class fWindow
|
class fWindowGL
|
class fDemo
|
class skroo (name of demo)
class cEffect
|
class cYourEffectName
The demo is organised by running effects which are read in from a
script file in an XML-like format.
LOADING:
1) The script is parsed by the XML code. It just stores a hierarhy
of tags, parameters and values.
2) The demo code starts to parse the XML hierarchy.
When it finds it will call the demo's doXML() funtion which
only understands specific tags.
3) The demo will ADD new effects that the script tells it to add.
It will "new" many different types of classes, but because all
the classes are derives from cEffect it only needs to keep
cEffect pointers.
4) The demo will call the effects doXML() function when it finds a
tag which has the same name as the effect name. This is how
effects get their parameters passed to them.
5) When tags are found the demo will add them to a list of
events. Events can either be triggered by time or by keypress.
The events keep a pointer to the XML kTag structure, so that
when the event is fire, the appropriate doXML() functions are
called.
6) The tag is hit to the demo will call all the effects load()
function.
7) The tag is hit, so the demo will enter the main loop.
EACH FRAME:
1) The events are checked to see if a new one needs to be preformed.
When one is, it will call the effects doXML() function and pass
in the changed parameters to it.
2) The drawlist of effects is gone through and each effects update()
and draW() function is called. The drawlist can be changed with
the tag.
3) Screen is flipped.
For your effects you should not load data with FOPEN ...
Rather use cMemoryStream or cFileStream. These work almost
exactally like fopen, but will allow us to change the location
of the data(eg, RAM/.RAR) etc..
--------------------------------------------------------------------
Here is a short tutorial on how camera works:
basically, you must first CREATE the camera like this:
this will create a camera called bob, and will give it a position. the cameras
rotation will be set to 0,0,0 by default. the cameras 'viewport' will be set
to fullscreen, the viewport is the area of the screen the camera will show in,
so 0,0,0.5,0.5 will mean it will only draw to a quater of the screen and will
appear in the top left corner. So you can also create a camera like:
once the camera is made you want to tell an effect to use it. If you have a
skybox effect:
and you can change the camera at any time:
but this will just give you a static camera..useful for somethings, but if you
want the camera to move you need to add keyframes. keyframes are snapshots of
camera settings at certain times, the camera will blend between these
keyframes. to specify keyframes:
t is TIME
pos is position (XYZ)
rot is rotation (XYZ)
this will make the camera go forward and then back, then forward then back.
it'll happen over 600 'frames'. The further apart the keyframes, the longer
it'll take to blend. at the end, it won't loop though, i need to add this
feature. You can also animate the cameras rotation:
this animation the camera will rotate around Z (like turning your head).
try it out, i have some EXAMPLES of this camera script being used:
http://www.rawhed.com/tmp/crazy_v3.rar
there are .txt log files for text, warning and errors...if something dies
check the log files..but it still might not help you ;)
////////////////////////////////////////////////////////////////////////////////
>videoplayer, mayaplayer - setframe
you can now set your frame in the videoplayer and the mayaplayer.
there are 2 parameters, 'frame' and 'play',
frame will set the frame number and play is an on/off(0/1) value
which will set the animation to play or stop.
so to pause at a frame:
or to pause at a specific frame:
and of course to start the playback again set play="1"
////////////////////////////////////////////////////////////////////////////////
>multi keymapping, support weird keys : " ;'. " etc..
i haven't fixed 'weird keys', but i found out why its not working
so i can fix it soon.
keybanks:
the demoengine has 10 keybanks( so thats 0..9, not 1..10 ) . you can add events to any of these banks.
the demoengine also keeps track of which is the current selected keybank.
will set the current bank to 0
will increase the current bank by 1
will increate the current bank by 3
will decrease the current bank by 2
whenever the current bank is less than zero, it will stop at 0, if it
goes higher than 9, it will stop at 9. the default keybank is 0.
also there is a change to the way events are specified:
easy... if you don't put the bank parameter it will default to -1,
-1 means it will work GLOBALLY, it doesn't matter what bank the current keybank
is set to.
so..here is an example of how to use it completely:
so keys 1,2,3 will change the current keybank
keys Q,W,E are events, but Q,W only work when you are on curtain current keybank
E will work no matter what your current keybank selected is.
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
//
// |>emo$ystem (Build: 02:25:43 Jan 21 2004)
// by rawhed/faktory^moOjUiCE^pht (c) 2002-2004
//
////////////////////////////////////////////////////////////////////////////
//
// wednesday 21-01-2004 (Build: 02:25:43 Jan 21 2004)
//
// + NEW FEATURES:
//
// + engine can now load .PNG!!
// even 32bit ones with alpha channel
//
// + upgraded to using BASS2.0 from 1.8a
//
// + sizing and positioning has been added to ALL
// effects, so now you have have your effects
// drawing to only regions of the screen instead
// of the whole screen always
//
// + noisetexture effect
// writes noise to a texture :)
//
// + added positioning example
// + added particlebox5 example
// + added texturenoise examples
//
// + fixed bug in gif player, crashed on exit
//
////////////////////////////////////////////////////////////////////////////
//
// monday 05-01-2004 (Build: 00:11:29 Jan 5 2004)
//
// + RANT
//
// + again another long gap in the updates :(
// + the engine was used for our demo for assembly03:
// 'feed your machine', after that there wasn't much
// time/energy for updates.
// + rava continues to use it for VJing in moscow, latvia and
// other places in europe.
//
// + API
//
// + improved plugin API..better design, more flexible
// + DRAMATICALLY reducted size of the main exe and ALL dlls
// this was done through not using libc.lib but rather
// using MSVCRT.DLL, MSVCPRT.DLL and also due to the
// better API design and use of pure virtual functions
//
// + NEW FEATURES:
//
// + improved keyboard input
// now all the special characters like !"£$@{}#' should work,
// as well as holding down SHIFT and having CAPSLOCK on.
//
// + buttons
// added clickable interactive buttons! this idea came
// from Reverie/Faktory^moOjUiCE. a demo called 'buttontest' is has
// been added to the demo section to show it. Its now possible
// to create simple mouse-driven apps with demosys!
//
// the buttons support actions for being clicked, going over,
// and leaving the buttons.
//
// + screengrabber
// create the effect, bind it to a key and u got a screengrabber =)
// writes to 32bit .bmp
//
// + 'wtf' effect
// by uttumuttu/Faktory
// a rather old effect now, but still cool!
//
// + BUG FIXES, MINOR CHANGES, ODDS & SODS
// + documentation updated, corrected and consolidated
// + new samples: 'snow_using_include', 'keybanks', 'screengrab'
// 'wtf'
// + elimatinated the tag..it was useless
// + all sorts of small optimisations and bugfixes to main engine
// including a crash bug where if texture wasn't found it would
// create a new texture but it called the function with the
// wrong params(i can't understand why the compiler didn't complain)
// + XML parser optimised and bug fixed
// now supports _ and numbers in tag names
// + can now add a keylog="0" to the demo param and it won't log the keys
//
////////////////////////////////////////////////////////////////////////////
//
// friday 11-07-2003
//
// + improved xml parser(handles spaces better, faster)
// can now do instead of
// + improved camera parameters, including looping ability
// pingpong with easein+out.
// + added animated gif support :) including transparent gifs
// + using a newer version of BASS
// + added an AVI writer effect!
// + added new examples for the new fx
//
////////////////////////////////////////////////////////////////////////////
//
// wednesday 04-06-2003
//
// been AGES since updated this..ARGH ;p lots has happened though
// here is a summary of what i can remember
//
// + added .md2 player effect
// + lockflash effect added (flashes your num/caps/scroll lock)
// + wavebox effected added
// + fogflash effect added
// + picture effect tiles now, useful for rotozoom
// + added 'camera' element, keyframing
// + added 'texture' element, textures can be reused etc..
// + now effects hold data about their variables which can
// be retrieved.
// + more examples!
// + added gridmap effect
// + added skybox effect
// + improved vis for musicplay effect
//
////////////////////////////////////////////////////////////////////////////
//
// wednesday 16-10-2002
//
// + added a doc about creating plugins
// + name="blah" actually changes the window title now(yay)
// + gave the exe an icon :)
// + added new effect skybox
// + started new "gridmap"
// + started a webcam plugin
// + added new effects to videoplayer and made it faster and
// more compatible.
// + added examples for videoplay, skycube, particlebox, clear,
// flash and others
//
//////////////////////////////////////////////////////////////////////////////
//
// friday 04-10-2002
//
// + added videoplayer effect
// + put keylogging back in
// + added more examples
//
////////////////////////////////////////////////////////////////////////////
//
// sunday 08-09-2002
//
// + removed all effects from main code, making things more modula.
// It now uses DLL plugins via the new command !
// This allows coders to add effects more easily. Had to
// change the directory structure and split libraries, but its
// much better now.
//
// + Made more script examples to help people learn
//
// + Made some code example for easily writing new plugins
//
// + It used to be that if you didn't specify a texture for an
// effect it would use white. Now it uses the last textureset.
// This allows a texture from effect1 to be used for effect2.
// You can make some nice effects using this.
//
//
//
////////////////////////////////////////////////////////////////////////////
//
// monday 26-08-2002
//
// + added vhs into the demo tag...setting this to 1 will let you FF
// and REW the demo
//
// + effect dogtail, has parameters: num and filename
//
// + added quicksort back in, so loading is faster
//
// + ALL effects now have these values:
//
//
//
// speed will make it go faster/slower ;) and active will just turn
// the effect on or off, even if its in the draworder list.
//
// + fixed some small bugs
//
// + ALL effects now have tweakable opengl values. But the effect
// itself can override the ones you set. Here is how it looks:
//
//
//
//
//
//
//
//
//
//
//
//
// + commenting is in there, use for comments..however
// there might be a bug..
//
// + can be used to include
// extra script files, so you can seperate them if you want.
//
////////////////////////////////////////////////////////////////////////////
//
// saturday 04-08-2002
//
// + made demo LICK_THE_EVERYTHING using demo engine
//
////////////////////////////////////////////////////////////////////////////
//
// thursday 25-07-2002
//
// + added new version of UT's LTREE effect. Leaves fall off of
// the tree - very nice :)
//
// + when scripting music filenames you no loader need to specify the path
//
// + better error handling..much less likely to crash if u don't have the
// data files.
//
// + XML parser tried to report bugs in the script
//
// + optimised. sync is much more accurate.
//
// + added sample="1" or "0" to musicplay effect (.wav files only)
// this will mean you can play the .wav file again and again and it
// will generate new channels to play it on.
// So if you bind a musicplay effect to a key that has sample="1"
// when you press the key before the sample has finished playing it
// will play it again...up to 16 channels per musisplay effect.
//
// + added active="1" or "0" to fontcool text. So you can specify all
// your lines of text but switch which are visible
//
// + particlebox has new parameters:
//
// spawndim="10,10,10" dimension particles can spawn in
// dirmin="-1,0,0" particle XYZ movement direction minrange
// dirmax="1,0,1" particle XYZ movement direction maxrange
// lifespan="100" average particle lifespan
//
////////////////////////////////////////////////////////////////////////////
//
// wednesday 18-07-2002
//
//
// + echo,flange,rotate,flangespeed added to musicplay effect
//
//
// + loopframe parameter added to 3dscene. This is the frame at which
// the animation will reset back to zero. If you don't want the
// animation to loop you should use 10000 or something super high :)
//
////////////////////////////////////////////////////////////////////////////
//
// sunday 14-07-2002
//
//
// + can pass parameter of the script you want to load
// eg:
// demo script2.txt
//
// + new effect: fontcool
//
// fontcool
// parameters:
// basefont="arial" (most windows TTF's)
// extrude="0.1" (Z amount to extrude, 0 = flat)
// italics="0"
// quality="0.1" (0 best,slowest -> 1 worst,fastest)
// commands:
//
//
// + new effect: particlebox
//
// particlebox
// paramaters:
// texture="blah.tga"
// number="500" (number of particleS)
// speed="1"
// dim="50,50,50" (dimensions of box)
// tra="0,0,0" (translation)
// rot="0,0,0" (rotation)
// sca="1,1,1" (scale)
// trainc="0,0,0" (ammount to increase translation by each frame)
// rotinc="0,0,0" (ammount to increase rotation by each frame)
// scainc="0,0,0" (cmmount to increase scale by each frame)
// pdir="0,0,0" (direction particles move in)
// prot="0,0,0" (rotation of particles)
// command:
// random (randomise particles)
// origin (bring all the origin)
//
// + 3dscene effect: added camera parameter to swap current camera
//
// + picture effect changed the translatin, rotation, scale
// to use this smaller format:
// tra="0,0,0"
// rot="0,0,0" (degrees)
// sca="1,1,1"
//
// + started work on new effect dogtail
// + bugs fixed
//
////////////////////////////////////////////////////////////////////////////
//
// monday 08-07-2002
//
//
// + musicplay now also supports these:
// filename="*.mtm,*.mo3,*.mp3,*.mp2,*.ogg,*.wav"
// + added trailval="1.0" to clear effect
// this will not clear the screen but just darken it.
// very useful for blurry additive effects and motion trails
//
////////////////////////////////////////////////////////////////////////////
//
// friday 05-07-2002
//
// + new effects from UT:
//
// starspace
// parameters:
// commands:
// teddy
// parameters:
// commands:
// ltree
// parameters:
// commands:
//
// + attack, sustain, decay added to flash(teels idea)
// + additive,subtracted, negative flash modes
//
// + picture effect R<->B bug fixed.
// + picture effect supports arbitary sized .tga now
// but they must be bigger then 8 and must an even number
// so 640x480 will work..it will divide the images up into
// segments of 256x256 or smaller.
//
// + engine speed has improved so the synchronisation will be more accurate
//
// + new effect: 3dscene
//
// 3dscene (no camera control..YET)
// paramaters:
// file="blah.zen"
// speed="0.4"
// timeoffset="0.0"
// frame="0.0"
// visible="1"
// commands:
// go
//
// still very basic..needs camera control added.
//
////////////////////////////////////////////////////////////////////////////
//
// + ramble
// + tutorial
// + todo list
// + change log
//
////////////////////////////////////////////////////////////////////////////
//
// + TODO LONGTERM
// + GUI
//
// + TODO SHORTTERM
//
// + get mayaplay fx working properly again
// + consolidate documentation
// + flash(.SWF) player
// still lacking some features, so it will get improved over
// time. Most notibly it lacks filled polygons, audio and
// bitmaps.
//
wanted:
+ viewports for effects and ability to scroll/zoom in them(picture effect zoom+scroll!)
+ how can i hold anim still and jump to some specific frame?
+ how can i define/control ground/sky
+ dif skybox movement
+ how can i change angle of camera for 3D anim?
+ how can i zoom it?
+ different camera movement for this one would be very handy as well.
+ another thing we should get a hold of is smoke. for the factory..
+ how about +/- things in the draworder? would it be possible with current
structure and interpretation of the script?
new stuff:
////////////////////////////////////////////////////////////////////////////////////////////
update fx: GRIDMAP:
this effect has some new presets. presets 0->14. some new funky distortions.
to use this effect:
////////////////////////////////////////////////////////////////////////////////////////////
new fx: LOCKFLASH:
flashes the Num & Caps & Scroll lock lights!!!!!
this is how to create it and let keys Q,W,E toggle the lights:
////////////////////////////////////////////////////////////////////////////////////////////
new fx: WAVEBOX:
sort of weird 3d wave effect, but can look totally different and weird by choosing right
parameters and using some strange textures and blending
here is how to create it:
the effect comes with 11 "presets" of wave shape. toggle these with preset="2" parameter
////////////////////////////////////////////////////////////////////////////////////////////
new engine: NEW TEXTURE HANDLING:
this allows you to load textures and then swap textures in effects.
wavebox is the only effect so far to use the engine NEW texture handler so far, but I'll change
the others to use it soooon.
here is how to use it:
to load some textures into engine:
then you can use these textures in wavebox effect:
////////////////////////////////////////////////////////////////////////////////////////////
new fx: FOGFLASH:
this is similar to the old 'flash' effect, but it uses the opengl FOG engine, this means in 3d
scenes the flash will start from the back and come to the front. Pretty neat.
you NEED the part because otherwise the FOG state won't be passed to the next effect.
there is one preset so far, which can be set with:
////////////////////////////////////////////////////////////////////////////////////////////
------------------------------------------------------------------------------
program
demo.exe scriptname.txt (defaults to script.txt)
------------------------------------------------------------------------------
script
demo
parameters:
name="q3view"
width="640"
height="480"
bpp="32"
fullscreen="0"
vhs="1" means you can click an FF/REW the demo
commands:
create
load
run
------------------------------------------------------------------------------
load
parameters:
effect="effectname"
This is the effect to play while loading is occuring.
This effect will be loaded first..so best if its small :)
------------------------------------------------------------------------------
event
paramaters:
time="0.0"
key="a"
trigger="a"
commands:
example:
------------------------------------------------------------------------------
draworder
paramaters:
effect="blah1"
effect="blah2"
effect="blah3"
commands:
example:
------------------------------------------------------------------------------
ALL EFFECTS have these:
xxx
parameters:
active="1" draw+update on/off, even if effect in draworder list
speed="1.0" multiplier for speed
they also all have a GL section:
this means that after the effect is run it will return
the original gl values. this should be used most of time
write to zbuffer
0=back, 1=front
0.0->1.0 if alpha channel pixel >= maskvalue then cutout
far clip plane
blend table
0 GL_ZERO
1 GL_ONE
2 GL_SRC_COLOR
3 GL_ONE_MINUS_SRC_COLOR
4 GL_SRC_ALPHA
5 GL_ONE_MINUS_SRC_ALPHA
6 GL_DST_ALPHA
7 GL_ONE_MINUS_DST_ALPHA
8 GL_DST_COLOR
9 GL_ONE_MINUS_DST_COLOR
------------------------------------------------------------------------------
clear
paramaters:
color="0xff112233"
trailval="0.0" (0.0->1.0)
commands:
example:
------------------------------------------------------------------------------
musicplay
paramaters:
filename="*.it,*.xm,*.mod,*.s3m,*.mtm,*.mo3,*.mp3,*.mp2,*.ogg,*.wav"
volume="1.0"
flange="0"
echo="0"
rotate="1"
flangespeed="0.0005"
sample="1" (only for .wav files, can play multiple times like for sfx)
commands:
play
stop
example:
------------------------------------------------------------------------------
flash
paramaters:
color="0xff112233"
attack="1.0"
sustain="1.0"
decay="1.0"
mode="0" (0=additive 1=subtractive 2=negative)
commands:
go
example:
------------------------------------------------------------------------------
picture (must be >8x8 and even width and height,24/32bpp)
paramaters:
filename="*.tga"
tra="0,0,0"
rot="0,0,0" (degrees)
sca="0,0,0"
commands:
example:
------------------------------------------------------------------------------
starspace
parameters:
commands:
example:
------------------------------------------------------------------------------
teddy
parameters:
commands:
example:
------------------------------------------------------------------------------
ltree
parameters:
commands:
example:
------------------------------------------------------------------------------
3dscene
paramaters:
filename="blah.zen"
speed="0.4"
timeoffset="0.0"
frame="0.0"
loopframe="90.0"
visible="1"
camera="camera01"
commands:
go
example:
------------------------------------------------------------------------------
fontcool
parameters:
basefont="arial" (most windows TTF's)
extrude="0.1" (Z amount to extrude, 0 = flat)
italics="0"
quality="0.1" (0 best,slowest -> 1 worst,fastest)
numtexts="1" (number of lines of text)
texture="blah.tga"
commands:
example:
------------------------------------------------------------------------------
particlebox
parameters:
texture="blah.tga"
number="500" (number of particleS)
speed="1"
dim="50,50,50" (dimensions of wrap box)
spawndim="10,10,10" (dimension particles can spawn in)
dirmin="-1,0,0" (particle XYZ movement direction minrange)
dirmax="1,0,1" (particle XYZ movement direction maxrange)
lifespan="100" (average particle lifespan, if you don't want a life span, don't write one)
tra="0,0,0" (translation)
rot="0,0,0" (rotation)
sca="1,1,1" (scale)
trainc="0,0,0" (ammount to increase translation by each frame)
rotinc="0,0,0" (ammount to increase rotation by each frame)
scainc="0,0,0" (cmmount to increase scale by each frame)
pdir="0,0,0" (direction particles move in)
prot="0,0,0" (rotation of particles)
color="0xff00ff00"
src="1" (blend)
dst="1" (blend)
command:
random (randomise particles)
origin (bring all the origin)
example:
------------------------------------------------------------------------------
dogtail
parameters:
num="4"
filename="texture.tga"
example:
------------------------------------------------------------------------------
videoplay
parameters:
filename="vid.avi"
example:
------------------------------------------------------------------------------
skybox
parameters:
camera="1"
file_front="1.tga"
file_back="2.tga"
file_top="3.tga"
file_bot="4.tga"
file_left="5.tga"
file_right="6.tga"
example:
------------------------------------------------------------------------------
<3dtree filename="tree.zen" speed="1"/>
<3dtree camera="cameraShape1" frame="0" play="1" loopmin="0" loopmax="400"/>
>