playerkeys(playerindex, newkey?, key1, key2, key3, ...)
~Check if a key is pressed by the player.
~'playerindex' is an integer count from 0, that is, 0 means 1p, 2 means 3p, etc.
~'newkey?', 0 if the keys are not new.
~key names:
"jump" "attack" "special" "esc" "start" "moveleft" "moveright" "moveup" "movedown" "screenshot" "anybutton"
~Any combination is allow, but no reason to use "anybutton" with others.
~Return 1 only when all buttons in list are pressed, keep in mind.
*NOTE* This method call is a bit buggy as of 8/8/2007. If not used in "key#.c" it will always return 0 unless newkey? = 0. If used to detect multiple keys, 1 will be returned if ANY of the specified keys are pressed.
playmusic(name, loop)
~Play a bor music.
~'name' is the path.
~'loop': 0 means dont loop, 1 means loop.
playsample(sample, prioroity, lvolume, rvolume, speed, loop)
~Play a defined sound sample.
~'sample' is a sample constant (see openborconstant()).
~'priority' is the playing priority.
~'lvolume' is left volume.
~'rvolume' is right volume.
~'speed' is the play speed.
~'loop': 0 = no loop, 1 = loop.
To play a sound with normal defaults used by the engine, use the following settings (this will play the beat sound): 'playsample(openborconstant("SAMPLE_BEAT"), 0, 120, 120, 100, 0);'
changepalette(index)
~Change current palette to specified one.
~'index' is an integer, 0 means default palette, 1-? can be any palette you loaded with command palette in level's .txt. If it is out of range, default will be used.
Only the onscreen entity's palette will change. Its icon (if any) will not.
killentity(entity)
~Kill the entity.
~'entity' is the entity you want to kill.
~This method wont display the entity's death animation, or any animation for that matter; the entity is removed instantly. If you want to kill an entity with death animation, use damageentity().
damageentity(entity, other, force, drop, type)
~Damage the entity.
~'entity' is the entity you want to damage.
~'other' who damage this entity, can be itself, if you specify a player's entity, score will be added. Default to the entity itself.
~'force' is the attack force. default to 1.
~'drop' is whether the attack knocks down the entity.
~'type' attack type, e.g., a shock attack or attack1-10, see openborconstant, the constants starts with 'ATK_'
findtarget(entity, int animnum)
~Returns handle of the nearest hostile entity.
~'entity' is the entity who?s nearest hostile you want to return. For example, if ?entity? is a PC, then the handle returned will be that of the nearest enemy character.
~animnum - Animation id. Optional. If it is given, the range values of the animation will be used to test if the target is in range.
Among other things, this is very useful for making range based or ?guided? attacks.
drawbox(x,y,width,height,z,color,alpha)
~draw a filled box with specified position and size.
~x,y: position values on screen
~width,height: size values.
~z: depth value, similar to setlayer command or entities, check it for details.
~color: color index in palette, check you palette.
~alpha: alpha blending effect from 1 to 6, this parameter is optional.
~return: none
drawline(x1,y1,x2,y2,z,color,alpha)
~draw a line from (x1, y1) to (x2, y2)
~x1, y1: position values of the start point.
~x2, y2: position values of the end point.
~z: depth value, similar to setlayer command or entities, check it for details.
~color: color index in palette, check you palette.
~alpha: alpha blending effect from 1 to 6, this parameter is optional.
~return: none
drawdot(x, y, z,color,alpha)
~draw a dot at (x, y)
~x, y: position values of the dot.
~z: depth value, similar to setlayer command or entities, check it for details.
~color: color index in palette, check you palette.
~alpha: alpha blending effect from 1 to 6, this parameter is optional.
allocscreen(width, height)
~Create a screen, return the handle. Basically you should call it in levelscript, but it is up to you. Be sure to store the handle or if you lose it you will not be able to free it, so it will take up memory until shut down. You can exit the engine normally and check the log to see if you forget to releas some of them.
drawlinetoscreen(screen, x1, y1, x2, y2, color, alpha);
~Similar to drawline, use the screen instead of the sprite queue. And also:
drawboxtoscreen(screen, x, y, width, height, color, alpha)
drawdottoscreen(screen, x, y, color, alpha)
free(handle)
Release a object created by script engine, it is now only available for the handle created by allocscreen, until we add some other dynamic alloc methods.
Basically you should call it in endlevelscript, but it is up to you.
drawscreen(screen, x, y, z,alpha)
~Draw current screen.
~x, y: position values of the coordination.
~z: depth value, similar to setlayer command or entities, check it for details.
~color: color index in palette, check you palette.
~alpha: alpha blending effect from 1 to 6, this parameter is optional.
jumptobranch(name, immediate)
~Go to branch by name. Branches is defined in levels.txt, check the manual for details.
~name: the branch name, must be those defined in levels.txt
~immediate: when set to 1, you will go to that level immediately if you are currently in a level, or else, you will still need to beat current level.
bindentity(entity, target, int x, int z, int a, int direction, int bindanimation)
~Bind entity to target, so the target moves, the entity moves.
~x, z, a: relative to target.
~direction: 0 no change 1 same direction as target -1 opposite direction as target 2 always right -2 always left
~bindanimation: 0 No effect. 1 Keep same animation as the target. 2 Also keep same frame as the target. 4 Kill the entity if the animation doesn't match.
~To unbind a entity, use bindentity(entity, NULL());
~Notice: You can combine those values for bindanimation, so it can be 6 which means 2 and 4.
changelight(int x, int z)
~Change light direction for gfxshadow.
~x, z: direction value, a positive x will make the shadow lean to the right, a positive z will make the shadow upward, or else they will be flipped.
~Give 256 or -256 to z will make the shadow as long as its owner.
~Try different values until you find the correct one.
changeshadowcolor(int colorindex)
~Change gfxshadow color.
~Note, gfxshadow use alpha 2, same as shadow.
changelevelproperty(name, propertyvalue)
~Change a property value of current level, this function is not quite completed.
~name can be:
~"rock", the given value must be an interger value or numeric value that can be converted to integer value. The rule is same as rock command in level file, check the manual for details.
loadmodel(name)
~"Load" a model that is currently set as "know" in models.txt.
~"name" is the model's name.
loadsprite(path, maskpath)
~Load a single sprite from the path specified and return the handle for later use.
~The maskpath parameter is optional; if given, it is a path to an
alpha mask for the sprite.
~You can free the sprite by calling script function free.
~Notice, the sprite will never be free automatically by the engine until the engine is about to shutdown so you have to keep the handle and free it manually later.
~Notice, the offset of the sprite will be always (0,0) like any regular icon and panel.
~Notice, the sprite is completely new, so if the path is used by an entity, there's not side effects if the entity model is unloaded.
drawsprite(sprite, int x, int y, int z, int sortid)
~Draw a sprite.
~Sprite must be a valid handle.
~x, y are the draw position.
~z is depth, sprite with a greater z value will appear above those with smaller z values.
~If more than one sprites use same z value, you need sortid to sort them, also, a greater value makes the sprite appear above others. In most situations, just use 0.
~See function setdrawmethod if you want to use special effects for the sprite.
~Notice: the sprite handle must be valid, that means if the sprite is removed already, an error might happen.
drawspritetoscreen(sprite, screen, int x, int y)
~Draw a sprite to a screen.
~sprite must be a valid handle.
~screen must be a valid handle returned by allocscreen.
~x, y are draw position.
~See function setdrawmethod if you want to use special effects for the sprite.
setdrawmethod(entity, int flag, int scalex, int scaley, int flipx, int flipy, int shiftx, int alpha, int colourmap, int fillcolour, int rotate, int rotateflip, int transparencybg)
~Set drawmethod for an entity or define a global drawmethod for other script functions.
~entity must be a valid entity handle or an empty value.
~All other parameters are optional.
~flag defines whether the drawmethod is active, when set to 0, the drawmethod will not take effect.
~scalex defines how the sprite will be stretch in x direction: sizex = original_sizex * scalex / 256
~scaley defines how the sprite will be stretch in y direction: sizey = original_sizey * scaley / 256
~flipx defines whether the sprite will be flipped left/right. 0 means don't flip and 1 means flip.
~flipy defines whether the sprite will be flipped top/bottom. 0 means don't flip and 1 means flip.
~shiftx defines how the sprite leans, like lightx in gfxshadow feature, in most situations you don't need this.
~alpha defines which alpha blending effect will be used. 0 means no alpha effect. -1 means the entity(if given) will use its own alpha value.
~colourmap(entity only) defines which colourmap will be used. 0 means no colourmap. -1 means the entity(if given) will use its current colourmap.
~fillcolour is the colour used by the entire sprite. 0 means don't fill the sprites.
~rotate is the rotate angle(clockwise), the range is from 0 to 359.
~rotateflip(entity only) means whether the entity will flip its rotate direction if the facing is changed.
~transparencybg(screen only) means whether the screen will use transparency colour.
~Notice: In 8bit mode, fillcolour is the index in palette, otherwise, it will be a RGB value which needs to be calculate first(no system functions available now).
~Notice: For screen, transparency colour is the first colour in palette(8bit) or pure black colour(which is also 0).
~Notice: If the entity parameter is an empty value, it will change the global drawmethod, and can be used by other script functions like drawsprite or drawscreen.
playgif(path, int x, int y, int noskip)
~Play a gif file as a cut scene, you can call it in game.
~path, the gif file path, like first parameter of command animation in scene txt.
~x, y position of the gif animation, like 2nd and 3rd parameters of command animation in scene txt.
~noskip, when set to 1, you can't press button to skip it.
~Notice: path is required. All other parameters are optional, and default value is 0.
~Notice: it needs some extra memory to play a gif file, about 75kb if the screen is 320x240/8bit.
checkrange(entity, target, int animid)
~Check if the given target is in range. Range, rangez, rangea of the specified animation will be used for checking.
~entity - animation owner. Must be a valid entity handle. Required.
~target - must be a valid entity handle. Required.
~animid - animation id. Optional. If it is not given, current animation will be used.
updateframe(entity, int frame)
~This method update current animation's frame number, a replacement of changeentityproperty(..., "animpos").
performattack(entity, int anim, int resetable)
~This method allow the entity to do an attack, not just give it attack animation.
~anim - Optional. It stands for animation number, can be got by openborconstant.
~resetable - Optional. If current animation number is same as this one, and resetable is 1, current animation will be reset or else, the anim will be ignored.
~Notice: If you provide anim parameter, and this function is called in an animation script, you probably need to add a return behind it because the animation might be changed and the animation script will be re-called.
setidle(entity, int anim, int resetable, int stalltime)
~This method change the entity back to idle status.
~anim - same as above. Optional. You probably will use idle animation, but that is up to you.
~resetable - same as above. Optional.
~stalltime - how long will current idle status last, in game tick. 200 will be about 1 second. Optional.
~Notice, idle status means the entity can change to other status automatically by the engine. So walk/run/idle can all be treated as idle.
~Also notice, you can set velocity for the entity later to simulate walk/run.
getentity(int index)
~Return entity by index.
~If this method succeeds it will return the entity handle, but be sure to check "exist" property by getentityproperty because it might be a dead one. If index is out of range, this function will return an empty value, make sure you check it if you are not sure.
~The range is from 0 to MAX_ENTS-1, you can get MAX_ENTS by openborconstant("MAX_ENTS")
~Notice, the entities are not always in same order, if you call it during a gameloop, it is safe, but if you use same index next time, the result might be different.
~MAX_ENTS is a large number, but most mods only have few entities on screen, so you should use openborvariant("ent_max") instead, it is a variable, so make sure you get it in different game loop.
Read more:
http://openbor.boards.net/index.cgi?board=scripthelp&action=display&thread=10#ixzz2FG6FZzD3
