Welcome, Guest. Please login or register.

Login with username, password and session length

 
Advanced search

1411196 Posts in 69314 Topics- by 58380 Members - Latest Member: feakk

March 19, 2024, 01:54:27 AM

Need hosting? Check out Digital Ocean
(more details in this thread)
TIGSource ForumsCommunityTownhallForum IssuesArchived subforums (read only)Archived ProjectsBalding's Quest (Moderator: BMcC)Balding's Quest: Scripting Guide
Pages: [1] 2
Print
Author Topic: Balding's Quest: Scripting Guide  (Read 14505 times)
BMcC
Senior Editor, Hero,
Moderator
Level 10
******

Bee Mixsy


View Profile WWW
« on: December 21, 2008, 11:37:00 PM »

What is BQ?  Go here.

The logic for all the objects in Balding's Quest is handled by Lua, with a set of script functions written by yours truly.  My goal is to have a system in place somewhere between programming and a game creation tool.  I tried to use plain English for the script functions, and Lua's syntax is much more readable than proper code, so I think this should allow even the relatively inexperienced to create their own objects!

For now, I'll just post a list of all the script functions, divided into categories, with all their parameters and brief descriptions.  If a parameter has a question mark next to it, it means it's optional.  (In LUA, you can pass as many params as you want.)  Get ready, there's lots:

G U I / G L O B A L   G A M E   S T U F F:

exitGame()
-- Exits the game

DEV_showNumber(Num)
-- A dev testing function: displays a value at the center of the screen

openTextBox(X?, Y?, Title?)
-- Opens the text entry box

closeTextBox()
-- Closes the text entry box

clearTextBox()
-- Clears the text entry box

getEnteredText()
-- Retrieves what's currently entered in the text box

setEnteredText(Text)
-- Sets what's entered in the text box

displayText(Text, X?, Y?, Alignment?)
-- Displays text.  There is only one display text per scripted object, and I think it's always aligned center (for now at least).

clearText()
-- Clears the object's display text.

setTextColor(R, G, B)
-- Sets the object's display text color.

F I L E S :

findFile(File_name, File_type)
-- Finds a file somewhere within the game's directory.
-- (Checks the map's root folder first, then the map /WhateverType, then the game's root folder /WhateverType.  I think.)
-- Returns the full file path with file name

setLocalDirectory(Directory)
-- I need to make this automatic, but this sets the root directory for the map (in case it's not in the Maps folder).
-- Useful for mods and such (check out the animation editor).

loadMap(Map_filename, Clear_data?, Fade_Type?, Fade_Time?, Load_delay?)
-- Loads a map and allows you to choose whether or not to clear the existing map and set various transition effects.

saveMap(Map_filename)
-- Saves the map file.

loadLastMap(Fade_Type?, Fade_Time?, Load_delay?)
-- Loads the last map loaded.

loadAnimFile(Anim_file, Object_pointer?)
-- Sets the object's animation file.  You could also pass it a pointer to a different object.

saveAnimFile(Anim_filename)
-- Saves an animation file.

getAnimName()
-- Returns the object's animation file name.

getName()
-- Returns the object's (script) name.

getMapName()
-- Returns the current map's name.

getObjectName(Object_pointer)
-- Returns a specific object's name.

O B J E C T   S E T U P :

setUpObject(
Animation file,
Top Height, Bottom Height,
Left Width, Right Width,
Direction,
Type,
State,
Heath,
Max Speed H,
Max Speed V,
Display Layer
)

-- The big all-in-one setup function you see at the start of most scripts.

M A I N   H A N D L E R   F U N C T I O N S :

handleDeath()
-- Runs the DEATH_SEQUENCE main script function if the object's health hits 0 or below.

handleMaxSpeed(Maxspeed_H?, Maxspeed_V?)
handleMaxSpeedH(Maxspeed_H?)
handleMaxSpeedV(Maxspeed_V?)

-- Caps the object's movement speed.

handleFriction(Amount?)
handleFrictionH(Amount?)
handleFrictionV(Amount?)

-- Reduces the object's speed until it stops.

handleMovement()
-- Moves the object based on its velocity, etc.

handleTileCollisions(Type?, Stop?)
-- Handles colliding with obstructions.  Generally, you don't want to pass any params to handler functions.

handleAttacks()
-- Handles being hit by "Attack" objects.

handleObjectCollisions(Object_pointer, Type?, Stop?)
-- Handles colliding with objects.
-- This should go in the OBJECTS_LOOP main script function, passing it the otherObj.

handleObjects()
-- Runs the OBJECTS_LOOP main script function, which automatically loops through every object.

handleGravity(Amount?)

-- Applies gravity.  Don't pass it a param and it will apply the map's current gravity.

O B J E C T S :

setFlag(Flag, True/False, Object?)
-- Sets a given flag for the object on or off.
-- (Flags and much more are defined in the INCLUDE_Objects.lua script.)

getFlag(Flag, Object?)

-- Returns the current state of a given flag.

setAllFlags(True/False)
-- Sets all flags to a given value.  Probably not needed.

getType(Object_pointer?)

-- Returns the Type of an object.

setObjectFocus(Object_pointer)
-- Lets you switch focus between the current script and other objects (provided you have a pointer, which the OBJECTS_LOOP can give you).
-- Very useful for advanced manipulation of other objects.

createObject(Object_name, X, Y)
-- Creates an object.  (Using the script name, without extension.)

destroyObject(Object_pointer?)
-- Deletes the object, or another object.

queueChild(Object_name, X, Y)
-- Creates a queued up child object.  Returns a unique ID for it.
-- NOTE: This stuff might not work anymore.

spawnChild(Child_ID, X, Y)

-- Like create object.  May not work anymore.

setSwitch(Switch_number, True/False)
-- Sets a map switch value on or off.
-- Useful for levers & doors, etc.
-- There are only 0-9 switches right now, I think.

getSwitch(Switch_number)

-- Returns true or false for the given switch.

skipObject()
-- Skips the rest of the logic for the current object.
-- Useful for "hiding" objects, disappearing/reappearing, whatever.

getStartValue()
-- Returns the Start Value set by the map editor.
-- Used in child scripts.

A T T A C K S :

collideAttack(Attack_pointer)
-- For the ATTACKS_LOOP main script function.  (Use thisAttack.)
-- Returns true/false for a collision, allows you to do special, specific stuff with Attacks.

spawnAttack(X, Y, Damage?, Direction?, Type?, Life?, Animation_file?, End_animation?)
-- Spawns an attack object.  Used for attacks (duh), but also other object-to-object interactions.

setAttackPhysics(Top_height, Bottom_Height, Left_Width, Right_Width, X_Acceleration?, Y_Acceleration?, X_Initial_Force?, Y_Initial_Force?, Gravity_amount?, Maxspeed_H?, Maxspeed_V?, Collisions_on?)
-- Sets the specs for the last created attack.
-- Nearly always called right after spawnAttack().

getRange(Start_X, Start_Y, Direction, Tile_type?)
-- Unless you pass a Type param, this finds the range (in pixels) from the point to an obstruction in the given direction.
-- The monocle beam and electric traps are an example of this.
-- I think it up and left will return a negative value.  I could change this if it bothers anyone.

P A R T I C L E S / E F F E C T S :

loadEffect(Animation_name)

-- Load your effects once at the beginning of the script.
-- Pass the animation filename (without extension) and it returns a pointer to this effect for future use.

spawnEffect(Effect_pointer, X, Y, X_Velocity?, Y_Velocity?, Life?, Collisions_on?)
-- Spawns an effect based on the effect pointer.
-- I may consolidate this with the attack objects so there are more physics options.
-- The particle plays until the animation is over or its Life expires (if Life is passed).

rotateEffect(Rotation, Flip_H, Flip_V)
-- Rotates and flips the last spawned effect.  Useful for getting more variety out of a single animation.

flashScreen(R, G, B, Time)
-- Flashes the screen once with a given color for the length of Time.

I N P U T :

keyPress(Key_code)
-- Returns if a key is being pressed or not.
-- (Look in INCLUDE_Objects to find the list of key codes.)
-- I'll add key configuration eventually.

mouseClickL()
mouseClickR()

-- Returns if the mouse has been clicked.

mousePosX()
mousePosY()

-- Returns the position of the mouse cursor.

mouseIsOver()
-- Returns true if the mouse cursor is over the object (based on the object's collision box, natch).

isClickedL()
isClickedR()

-- Returns if the object is clicked by the mouse cursor.

P H Y S I C S :

clearMovement()
-- Clears the object's physics values.

setMaxSpeedH(Maxspeed_H)
setMaxSpeedV(Maxspeed_H)

-- Sets the horizontal and vertical max speeds used by the handleMaxSpeed functions.

getMaxSpeedH()
getMaxSpeedV()

-- Returns the current Horizontal and Vertical max speeds.

addVelX(Amount)
addVelY(Amount)
setVelX(Amount)
setVelY(Amount)

-- Adds or sets the object's X or Y velocity.
-- You should typically only use Acceleration to manipulate objects.
getVelX()
getVelY()

-- Returns the object's current X or Y velocity.

addAccelX(Amount)
addAccelY(Amount)
setAccelX(Amount)
setAccelY(Amount)

-- Adds or sets the object's X or Y acceleration.
-- You should typically only use Acceleration to manipulate objects.
getAccelX()
getAccelY()

-- Returns the object's current X or Y acceleration.

P O S I T I O N :

addPosX(Amount)
addPosY(Amount)
setPos(X?, Y?)
setPosX(X)
setPosY(Y)

-- Adds to or sets the object's X or Y position.

getPos()
-- Returns the object's X and Y position.
getPosX()
getPosY()

-- Returns the object's X or Y position.

getDir()
-- Returns the object's direction.
setDir()
-- Sets the object's direction.

C O L L I S I O N S :

setCollisionBox(Top_height, Bottom_height, Left_width, Right_width)
-- Sets the collision box for the object, with its X,Y position at its center.

getTopH()
getBottomH()
getLeftW()
getRightW()

-- Returns the dimensions of the object's collision box.
-- (Top height, bottom height, left width, or right width.)
setTopH(Top_height)
setBottomH(Bottom_height)
setLeftW(Left_Width)
setRightW(Right_Width)

-- Sets the dimensions of the object's collision box.

collide(Direction)
-- Returns true or false for a collision in a given direction.
-- NOTE: This DOES NOT test for a collision.  It just returns if the object has collided within the last loop.
-- That means it should be called after handleTileCollisions and collideObject (in the OBJECTS_LOOP main function).

setCollisionFlag(Direction, True/False)
-- Forces a collision flag for the object in a given direction on or off.
-- This should be avoided unless being used in a very special case.

collideTile(Direction, Stop?, Type?, X_shift?, Y_shift?)
-- Returns true if the object collides with a specific tile (platform Type by default) in a given direction.
-- You can also shift the collision box temporarily for the test.

collideObject(Direction, Object_pointer, Stop?, Type?, X_shift?, Y_shift?)

-- Like collideTile, but tests against the object pointed to.

collideLedge(Direction, Type?)
-- My one HACK function, to test for ledges.  I'm not sure if I even use this anymore...
-- I'll leave it here for posterity.

T I L E S :

getTileType(X, Y, In_pixels?)
setTileType(X, Y, Type, In_pixels?)

-- Gets and sets the tile Type of a tile in the map array.
-- (Test for Water, Ladder, Platform, etc.)

getTileGfx(X, Y, In_pixels?)
setTileGfx(X, Y, Tile_graphics_number, In_pixels?)

-- Gets and sets the 8x8 tile graphics number (based on the tilesheet) of the current tile in the map array.

getTileBG(X, Y, In_pixels?)
setTileBG(X, Y, True/False, In_pixels?)

-- Gets and sets the layer of a tile in the map array (background or foreground).

getTileRot(X, Y, In_pixels?)
setTileRot(X, Y, Rotation, In_pixels?)

-- Gets and sets the rotation of a tile in the map array.

S T A T E   M A C H I N E :

setState(State)
-- Sets the object's State.
-- (This will run the main script function EXIT_STATE on the current state then ENTER_STATE on the new state automatically.)

getState()
-- Returns the current State of the object.

S O U N D S :

loadSound(Sound_filename)

-- Like Effects, load the sound once at the beginning of the script and use the returned pointer to play it.

playSound(Sound_pointer, Volume?)
-- Plays the passed sound.  Volume is iffy until I upgrade the audio library.

getMusicTime()
-- Get the position of the currently played background music (in MS, I think).

A N I M A T I O N S :

playAnim(Animation_number?, Force?)
pauseAnim(True/False?)
stopAnim()

-- Plays, Pauses, or Stops the animation.

getAnim()
setAnim(Animation_number)

-- Gets or sets the current animation.

getFrame()
setFrame(Frame_number)

-- Gets or sets the current frame.

getFrameLength(Frame?)
-- Gets the length of the current (or a specific) frame in the current animation.
setFrameLength(Frame, Length)
-- Sets the length of specific frame in the current animation.

getAnimCounter()
setAnimCounter(Time)

-- Gets and sets the counter for the object's animations.

getNumberOfFrames()
getNumberOfAnimations()

-- Returns the number of Frames/Animations in the object's animation file.

getFlipH()
setFlipH(True/False)

-- Gets and sets the object's horizontal flip.
flipH()
-- Flips the object horizontally.

getFlipV()
setFlipV(True/False)

-- Gets and sets the object's vertical flip.
flipV()
-- Flips the object vertically.

getRot(Rotation)
setRot(Rotation)

-- Gets and sets the object's rotation.

rotL()
rotR()

-- Rotates the object Left or Right.

getAnimOffsetX()
setAnimOffsetX(Offset_X)

-- Gets and sets the object's animation x offset.

getAnimOffsetY()
setAnimOffsetY(Offset_Y)

-- Gets and sets the object's animation y offset.

H E A L T H :

getHP(Object_pointer?)
setHP(Object_pointer?)
addHP(Object_pointer?)

-- Returns, sets, or adds to the HP of the object (or another object).
« Last Edit: March 10, 2009, 09:02:12 AM by BMcC » Logged

BMcC
Senior Editor, Hero,
Moderator
Level 10
******

Bee Mixsy


View Profile WWW
« Reply #1 on: December 21, 2008, 11:38:23 PM »

Okay.  Gotta fill this out.
« Last Edit: February 26, 2009, 11:26:54 AM by BMcC » Logged

Mr. Yes
Level 5
*****



View Profile WWW
« Reply #2 on: December 22, 2008, 02:44:06 AM »

Nice! Even if they're not filled out this should make for a handy reference in the meantime. Good luck completing this.
Logged

BMcC
Senior Editor, Hero,
Moderator
Level 10
******

Bee Mixsy


View Profile WWW
« Reply #3 on: December 22, 2008, 04:02:55 AM »

Good luck indeed!  I actually worked on the game itself instead of finishing this.  But soon!
Logged

mike
Level 0
***


View Profile
« Reply #4 on: December 24, 2008, 09:34:21 PM »

So, while I was messing around with the scripts earlier, I thought it'd be cool for an object to be able to modify or read the properties of another object. Say, an object for displaying what the selected item is (like Monocle, or Kick).

I first tried doing by directly accessing the property "currentItem" in the Guy object upon collision.
Code:
function OBJECTS_LOOP(thisObj, otherObj)
--handleObjectCollisions(otherObj)
item = ""
if getType(otherObj) == OBJ_PLAYER then
setObjectFocus(otherObj)
tX = getPosX()
tY = getPosY() - getTopH()
if currentItem == 1 then
item = "MONOCLE"
elseif currentItem == 0 then
item = "KICK"
end
setObjectFocus(thisObj)
displayText(item,tX , tY - 10)
end
end
The above code crashed out Sad. So I tried something else:
Code:
function OBJECTS_LOOP(thisObj, otherObj)
--handleObjectCollisions(otherObj)
item = ""
if getType(otherObj) == OBJ_PLAYER then
setObjectFocus(otherObj)
tX = getPosX()
tY = getPosY() - getTopH()
if getCurrentItem() == 1 then
item = "MONOCLE"
elseif getCurrentItem() == 0 then
item = "KICK"
end
setObjectFocus(thisObj)
displayText(item,tX , tY - 10)
end
end
Code: ("Inside the Guy.lua file")
function getCurrentItem()
return currentItem
end
The above had some strange effects, but did not work. Huh?

I tried something else that would report Guys current state (using the getState() func) and it worked flawlessly.  Roll Eyes

My question is, is there a way to make this work (for any objects, not just Guy etc.)?
I think it would be good to be able to abstract pickups etc in a way that they could take advantage of this sort of object property interaction.

Anyway, just academic at this point, but I thought it was worth bringing up.

Thanks. Wink
Logged
increpare
Guest
« Reply #5 on: December 26, 2008, 04:01:34 AM »

Just tried modifying the vertical moving platform to make it horizontal; it was quite a pleasant experience!  I'll keep an eye on things as they develop, though am pretty busy atm :/
Logged
BMcC
Senior Editor, Hero,
Moderator
Level 10
******

Bee Mixsy


View Profile WWW
« Reply #6 on: December 26, 2008, 04:52:48 PM »

@mike: Yeah, all the script functions are written by me, so if it's not in the list, it won't do anything.  And you can't access variables created locally for the Lua scripts (that I know of), unfortunately.  I need to add some way for objects to better transfer information to eachother...  I'll ask Alec about it.

@increpare: Cool!  Yeah, I hope you create some stuff when you have some free time.  It'll get easier and easier with each build. Wink
Logged

Hideous
That's cool.
Level 10
*****


3D models are the best


View Profile WWW
« Reply #7 on: January 07, 2009, 08:43:30 AM »

There's no info here yet? For shame! Outraged

(but i still love you brondon)
Logged

Bennett
Jinky Jonky and the Spell of the Advergamez 3
Level 10
*



View Profile
« Reply #8 on: January 07, 2009, 09:26:05 AM »

Yeah, at least put the parameters in. I have an idea for a level but I want to make sure that it can be done, script-wise, before I start making tiles.
Logged
BMcC
Senior Editor, Hero,
Moderator
Level 10
******

Bee Mixsy


View Profile WWW
« Reply #9 on: January 07, 2009, 10:47:24 AM »

I'm sure it can, Benzido!

But yeah, you guys called me on it.  I've totally been putting this off.

I'll start filling it out tonight. Wink
Logged

Rostiger
Pixelhead
Level 5
******



View Profile WWW
« Reply #10 on: January 07, 2009, 11:28:19 AM »

Yeah, at least put the parameters in.

Yeah, I mean, sheesh, Brandon, how about getting some work done?  Roll Eyes

[EDIT]Crap, sarcasm is hard to get across online...[/EDIT]
« Last Edit: January 07, 2009, 01:03:08 PM by Kovski » Logged

Clemens Scott
Co-Founder & Artist of Broken Rules
BMcC
Senior Editor, Hero,
Moderator
Level 10
******

Bee Mixsy


View Profile WWW
« Reply #11 on: January 07, 2009, 12:03:32 PM »

Haha, I have very little motivation for writing documentation. Embarrassed

Balding's Quest is actually a pretty tough project for me because of stuff like that.
Logged

Hideous
That's cool.
Level 10
*****


3D models are the best


View Profile WWW
« Reply #12 on: January 08, 2009, 12:27:33 PM »

Is it tonight yet? Durr...?
Logged

BMcC
Senior Editor, Hero,
Moderator
Level 10
******

Bee Mixsy


View Profile WWW
« Reply #13 on: February 26, 2009, 08:26:07 AM »

IT'S TONIGHT NOW.

Look!  I'm filling in the scripting guide. Hand Fork Left

EDIT:  IT'S DONE.
« Last Edit: February 26, 2009, 03:04:24 PM by BMcC » Logged

Alec
Level 10
*****



View Profile WWW
« Reply #14 on: February 27, 2009, 03:51:36 PM »

IT'S TONIGHT NOW.

Look!  I'm filling in the scripting guide. Hand Fork Left

EDIT:  IT'S DONE.
Shocked
Logged

BMcC
Senior Editor, Hero,
Moderator
Level 10
******

Bee Mixsy


View Profile WWW
« Reply #15 on: February 27, 2009, 04:11:13 PM »

Hahaha, yes yes, I actually did it.  It's the kind of tedious work I love so much.  Just so much.

So, uh... made any, um... scripts lately? Well, hello there!
Logged

Bennett
Jinky Jonky and the Spell of the Advergamez 3
Level 10
*



View Profile
« Reply #16 on: March 01, 2009, 07:45:45 PM »

So, maybe this is a stupid question, but are there any example scripts? I'd like to implement Track 'n Field in BQ.
Logged
BMcC
Senior Editor, Hero,
Moderator
Level 10
******

Bee Mixsy


View Profile WWW
« Reply #17 on: March 01, 2009, 08:13:20 PM »

Every object in the game is in the Scripts folder, from Guy to Box.  And NEW_OBJECT is an empty script with all the main functions.

Good luck!
Logged

eerr
Level 0
***


View Profile
« Reply #18 on: March 09, 2009, 04:34:17 PM »

is there a way to determine if an object stopped moving only because of terrain?
is there a good way to assign which sprite should be displayed out of 18 unique?


I'm trying to write an extremely complex projectile(Horror Spike) that flies in an arc, and can pin people (and items) to the wall or floor

edit: crap, I really badly want to stick this in a game, but I still should have started by reading the code first.

edit2: the pieces are falling into place, if I use math.atan2(x,y)(awesome lua command) it should return the correct rotation... for the rotation effect on a square sprite.


things I know I have  left to do are translate it to lua,implement a sample constructor, 
and create the hitbox() methods.
« Last Edit: March 09, 2009, 11:53:36 PM by eerr » Logged
BMcC
Senior Editor, Hero,
Moderator
Level 10
******

Bee Mixsy


View Profile WWW
« Reply #19 on: March 10, 2009, 08:57:50 AM »

I'm not 100% sure you meant to post here, but--

is there a way to determine if an object stopped moving only because of terrain?
An object will only stop moving if you tell it to in its script.  You could easily take note of the collisions after checking the tile map, but before checking objects.

is there a good way to assign which sprite should be displayed out of 18 unique?
Hm, what exactly do you mean?  At the start of a script you type in which animation file it'll load.  If you want it to be randomized, you could have a list of file names to pick from, similar to the Game Over script (Fail.lua).  Or maybe you mean 18 animations, in which case you'd only need one animation file, and you could set the animation number randomly.  Or maybe you mean 18 frames?  Anyway, yeah, of course.

I'm trying to write an extremely complex projectile(Horror Spike) that flies in an arc, and can pin people (and items) to the wall or floor
Haha, okay. Smiley

edit2: the pieces are falling into place, if I use math.atan2(x,y)(awesome lua command) it should return the correct rotation... for the rotation effect on a square sprite.
At the moment I haven't provided script access to full sprite rotation (only 90 degree angles and flip), 'cause I didn't think it'd be fitting for BQ.  But if there's something awesome enough, I could open it up, I guess.  (Or you could "fake" it with animations, which would look better anyway.)

things I know I have  left to do are translate it to lua,implement a sample constructor, 
and create the hitbox() methods.
What are you working in, if not LUA?  And what do you mean "hitbox() methods?"  There are already Collision and Attack systems in place.

Hope this helps.
Logged

Pages: [1] 2
Print
Jump to:  

Theme orange-lt created by panic