Object List – Specific to the Dagon Engine

General to all Objects

• object:setFadeLevel(??)
• Not tested...
• object:setFadeSpeed(speed)
• speed is one of the following {SLOWEST, SLOW, FAST, FASTEST}
• object:setName(“name”)
• Not tested
• object:setDefaultFadeLevel(??)
• Not tested

Room Object

• room "name"

  • Creates a Room object and builds up all the Nodes and Slides in that room file. Creates the objects on the first call, but only references on later calls.
  • 'name' is both the name of a .lua file and defines the name of the room being created.
  • The default location for all room files is project/Rooms folder.
  • This is one of the few Dagon instructions that doesn't seem to conform to any LUA interpretation.
  • Rooms are top-level objects but are not directly visible as they have no graphics of their own.
  • All Nodes or Slides that are created must be done so inside a room file.
  • If a room file needs to reference something from another room file, use the room "name" command at the beginning of the file. This will cause that room to be loaded first, if not already loaded. Already loaded rooms will not be duplicated.

• Audio object = room:addAudio(Audio object)

• Adds an audio object to a room. Could be a music layer or a sound effect. Audio added to a room will play when the room is occupied, unless it is turned off. See Audio objects for dealing with the details.

• room:setDefaultFootstep(Audio object or audio filename?)

• Default sound whenever a move is performed, if not defined in a node.

• Timer object = room:startTimer(seconds,loop option, function())

• When the Timer is started, it counts down from 'seconds' and calls the 'function()' when it hits zero.

• If the loop option reads 'loop = true', timer will automatically start over

• (not clear)Timer runs whenever the room is entered, otherwise not. (auto = true?)

• See Timer objects for details

• Room object = currentRoom()

• Gets the current room being occupied

Node Object

• Node object = Node(“name", "description")
• 'name' is the exact filename, without suffix, of the *.tex file packed with 6 cube-face images.
• if 'bundleEnabled = false' is set in Dagon.cfg, 6 individual image files will be loaded as follows:
  In Dagon.cfg you must also set texTextension = "jpg", "png" or "tga", whatever your files are.
  Files should be in the Resources/Nodes folder.
  Each file name should be the form "name001" for the north cube face, "name002" for the east face, etc. (1-6 correspond to N,E,S,W,U,D)
• See Node Textures for details.
• Default location for the 'name' files: project/Resources/Nodes folder
• 'description' is a text that can be used for whatever (?)
• node:setDescription(“description”)
• sets or changes the node’s description text. Used whenever a short description text is needed.
• Text = node:description()
• Get the node’s description
• node:link(table of autolink directions = node (or slide?) objects)
• This is a shortcut method that allows general mouse-click navigation without explicitly adding spots.
• example: node:link({N=node1, S=node3, etc}).....note the brackets
• Available direction values {N,S,E,W,U,D,NE,SE,NW,SW}.....(the order does not matter)
• Spot object = node:addSpot(Spot object))
• Adds a spot to the node. Spot details are specified within the Spot object. See Spot object for details.
• node:disable()
• Turns off the mouse interaction, cursor disappears, and node background and audio are blanked.
• node object = currentNode()
• Returns the current Node being occupied.
• timer object = node:startTimer(seconds, loop option, function())
• When the Timer is started, it counts down from 'seconds' and calls the 'function()' when it hits zero.
• If the loop option reads 'loop = true', timer will automatically start over
• (not clear)Timer runs whenever the node is entered, otherwise not. (auto = true?)
• See Timer objects for details
• node:setDefaultFootstep(Audio object or audio filename?)
• Sets the default footstep sound when movement occurs. Overrides any default sound set for the current room.

Slide object

• Slide object = Slide("picture filename", "description")
• Slide objects are similar to Node objects with most of the same capabilities with exceptions:
  • The spot outline table is in image coordinates, not cube face.
  • No autolinking (??)
  • Transition styles ??? Fade speeds?
  • currentNode() command returns the picture filename

Spot Object

• Spot object = Spot(value from Spot direction table, Outline table, table of options)
• Creates a Spot object, but note that it only describes the shape, direction, and general behavior.
• Available directions: NORTH, EAST, WEST, SOUTH, UP, DOWN
• Outline table = table of x,y coordinate pairs on a cube face to define the spot's location and shape.
  Coordinates are with respect to the upper left corner of cube face.
  Note that Spots with audio objects will place them at the first coordinate pair specified.
  Example: {x1,y1,x2,y2,x3,y3, x4,y4} would make a 4-sided block. Example: {x1,y1} would indicate location of an audio source. It will pan with the camera.
  ??? What happens if the order is out of sequence and does not cleanly trace the outline?
• Because Spots can contain a number of object types: audio, feed, video, etc, then the table of options can contain any combination of values intended for an object that is or will be attached. Otherwise they are ignored. These values become the default value for attached objects unless the attached objects themselves have had an option set.
• auto = true/false Activates as soon as the player enters the node.
• volume = 0 to 100
• sync = true/false Indicates whether the engine should wait until the video stops playing or not.
• loop = true/false Loops the attached video or audio.
• type object = spot:attach(Spot type, filename or object)
• ?? ‘type object’ is whatever the object type that was attached.
• ?? Filename or object depends on what the Spot type was used
• See Spot types below for details of each
• spot:disable()
• Makes the spot inactive and invisible and inaudible?
• Spot will remain unresponsive unless it is enabled()
• spot:enable()
• Activates the spot so that when clicked it performs any actions attributed to it.
• spot:start()
• Runs the spots functions, audio, video, etc.
• spot:stop()
• Stops all of the spots functions, audio, and video.
• spot:setCursor(cursor type)
• Sets the default cursor whenever mouse hovers over a spot.
• See table of cursor types
• spot:play()
• Causes the video, audio, functions, etc. that are attached to a spot to start playing
• boolean = spot:isPlaying()
• Returns whether a spot is playing.
• Spot types:
• AUDIO
  Attaches an audio object to the spot, see audio objects for options than can follow.
• VIDEO
  Attaches a video object to the spot, see audio objects for options than can follow.
• IMAGE
  Attaches an image to the spot, see audio objects for options than can follow.
• FEED
  Attaches a Feed function to the spot. Feed adds text to the bottom of the screen using the Feed() function, which is not in the Engine but a script module. (need to add what info follows the keyword)
• SWITCH
• Attaches the room/node/slide switch() command to the spot.
• FUNCTION
• Attaches a custom user-defined function to the spot.

Overlay

• Overlay object = Overlay('name')
• Creates an Overlay object with the given name.
• overlay:addButton(Button object)
• Adds a Button object to the overlay
• overlay:enable()
• Turns on display and mouse interactions
• overlay:disable()
• Turns off display and mouse interactions
• overlay:move(x, y)
• Move location of Overlay object relative to current position (a ‘shift’, does not remember old position)
• overlay:fadeIn()
• Like enable, but uses Fade settings, see general object settings
• overlay:fadeOut()
• like disable, but uses Fade settings, see general object settings
• overlay:setPosition(x,y)
• move upper left corner position of overlay to x,y in screen coordinates
• attached buttons and images will move with it
• overlay:addImage(Image object)
• Adds an Image object to the overlay
• Image position is relative to upper left corner position of overlay
• pos x, pos y = overlay:position()
• returns the screen position of the upper-left corner of the overlay

Image

• Image object = Image(image “filename”)

• Creates an Image Object. Note, must be attached to an Overlay.

• image:setPosition(x,y)

• sets image position in screen pixels relative to containing overlay

• pos x, pos y = image: position()

• gets position of image relative to containing overlay

• image:move(x,y)

• moves image relative to current position in pixels.

• image:setSize((x,y)

• sets image size in screen pixels

• size x, size y = image:size()

• gets image size in screen pixels

• image:scale(multiplier)

• changes size of image by a factor. Multiplier = 1 is no change.

• image:disable()

• image off

• image:enable()

• image on

• Button

• button object = Button(x pos, y pos, x size, y size)

  • position is relative to containing overlay

• size is in screen pixels

• button:setAction(type, function object)

• type of behavior when clicked

• FUNCTION, followed by a function()

• SWITCH, followed by a room or node

• FEED, followed by text (, and optional audio ???)

• button:setCursor(cursor object)

• cursor when mouse hovers over button

• button:setImage(image filename)

• image for button (does not use an Image object)

• button:setSize(x,y)

• size in screen pixels

• button:scale(multiplier)

• changes size of image by a factor. Multiplier = 1 is no change. Does not remember old size.

• button:setPosition(x,y)

• position in screen pixels relative to containing overlay

• size x, size y = button:size()

• gets button size in screen pixels

• pos x, pos y = button:position()

• gets buttons position in screen pixels relative to containing overlay

• text = button:text()

• gets text displayed by button

• button:setText(“text”)

• sets text displayed by button

• button:setFont(font filename, size)

• sets default font for the overlay, and the font size

• button:setTextColor(0xAARRGGBB)

• color for the default overlay.

• Format is alpha, red, green blue for each two characters. FF is max, 00 minimum.

• button:fadeIn()

• uses object’s fade settings

• button:fadeout()

• uses objects fade settings

Timer

• Timer object = startTimer(seconds, loop flag, function())
• stopTimer(Timer object)
• probably can access other timer methods and properties...what are they?

Audio

• audio object = Audio(filename, [table of audio options])
• creates an Audio object, optional table of audio options, see below
• audio:setFadeSpeed(value from FadeSpeed table)
• audio:match(another audio handle)
• audio.loop = true or false
• audio.volume = 0 to 100
• audio options:
• loop = true/false
• volume = 0 to 100
• sync = true/false (The engine waits until the audio finishes playing or not.)

Video (this is a mess, I basically have no information)

• Video object = Video(auto,loop,sync)
• Creates a Video object
• loop = true/false (Should the video loop or play once and stop.)
• volume = 0 to 100
• sync = true/false (The engine waits until the video finishes playing or not.)
  // Checks

o bool doesAutoplay(); o bool hasNewFrame();
o bool hasResource();
o bool isLoaded();
o bool isLoopable();
o bool isPlaying();
o bool isSynced();
o
o // Gets
o
o DGFrame* currentFrame();
o const char* resource();
o
o // Sets
o
o void setAutoplay(bool autoplay);
o void setLoopable(bool loopable);
o void setResource(const char* fromFileName);
o void setSynced(bool synced);
o
o // State changes
o
o void load();
o void play();
o void pause();
o void stop();
o void unload();
o void update();
o

---

Libraries in Dagon

Libraries in Dagon are for general non-object commands and use a '.' as the separator. They can be accessed from anywhere.
The four libraries are 'cursor', 'effects', 'config' and 'camera'

• Cursor

• cursor.load(type, “image filename”)

• cursor.disable()

• cursor.enable()

• cursor-type table {NORMAL, DRAGGING, LEFT, RIGHT, UP, DOWN, UP_LEFT, UP_RIGHT, DOWN_LEFT, DOWN_RIGHT, FORWARD, BACKWARD, USE, LOOK, TALK, CUSTOM}

• Screen FX
  These effects take effect immediately. Need info on some of the accepted ranges....?

• effects.throbstyle = n to m ?

• effects.throb = 0 to 100

• effects.motionBlur = 700 ?

• effects.sharpen = 50 ?

• effects.brightness = 150 ?

• effects.contrast = 120 ?

• effects.saturation = 0 to 100

• effects.noise = 0 to 100

• effects.sepia = 0 to 100

• Engine Configuration
  General configuration of the engine. At least some of these will have no effect after the first script is called and must set as describe for the Dagon.cfg file. (needs testing)
  Many of these can be read, not tested though..

• config.controlMode = value from Control Mode table

• config.debugMode = true/false

• config.displayWidth = number of pixels

• config.displayHeight = number of pixels

• config.effects = true/false

• config.fullScreen = true/false

• config.log = true/false

• config.showSplash = true/false

• config.verticalSync = true/false

• config.antialiasing = true/false

• config.autorun = true/false

• config.displayDepth = ???

• config.dust = ?

• config.framebuffer = ???

• config.framerate = frames/sec value

• config.mute = true/false

• config.showHelpers = true/false

• config.showSpots = true/false

• config.scare = ???

• config.breath = true/false ....gives camera a breathing movement

• config.walk = true/false ....gives camera a bob during node transitions

• Camera Tools
  Diverse set of tools that affect the viewport camera

• camera.fov = deg .... sets the field-of-view in degrees. Usable range is 5 to 165. Can also be read.

Top-Level Dagon Commands

All of these commands can be called from anywhere

• Node object = currentNode()
• Returns the current Node object occupied, or picture filename if in a Slide
• Room object = currentRoom()
• Returns the current Room object occupied
• play(filename)
• Immediately executes the file, whether an audio or a video
• lookAt(value from Direction table)
• Moves the camera view to the direction indicated
• switch(node object or room object)
• Immediately loads the node indicated, or the default node if a room is indicated.
• feed(text, audio file or object?)
• Causes a text message to appear on the screen, accompanied by the optional audio
• sleep(timer value in seconds)
• Causes the player’s dog to fall asleep for the seconds indicated
• timer object = startTimer(seconds, loop option, function())
• Manually starts a new Timer with the given options and returns the Timer object for reference later.
• register(value from Event table, function())
• Sets up a function to be called whenever the event occurs
• setFont(FEED,font filename, font size)
• Sets or changes the font used by the Feed mechanism
• hotkey(value from Hotkey table, function())
• Assigns a function to a keyboard key that is called whenever it is pressed.
• snap()
• Saves a screenshot (with timestamp) to the project folder as a TGA file.

Dagon.cfg Commands

• antialiasing = true/false
• not working
• autopaths = true/false
• must provide paths if false..
• if true..these subfolders should exist in the main (project) folder
• Modules/ -all lua files not rooms
• Resources/Audio/ -audio files
• Resources/Cursors/ -cursor images
• Resources/Fonts/ -font files
• Resources/Images/ -image files
• Resources/Nodes -image files for cube faces
• Rooms/ -all the lua files that create rooms
• Resources/Video -video files
• must provide paths if false.. (how?)
• autorun = true/false
• will cause Dagon to not run, what is the use?
• controlMode = FIXED, DRAG, OR FREE
• sets control method with mouse.
• debugMode = true/false
• enables debug HUD and console
• displayWidth = size in pixels
• if done in full-screen mode, will push to upper left corner
• displayHeight = size in pixels
• if done in full-screen mode, will push to upper left corner
• displayDepth = 8, 16, 24, 32 ?????
• framebuffer = true/false
• framerate = true/false
• effects = true/false
• fullscreen = true/false
• will override config’d resolution to fit monitor or OS display setting
• log = true/false
• saves console information to a Dagon.log file.
• mute = true/false
• controls all audio output
• script = "filename" where filename is initial *.lua file that is called.
• Must be in same folder as Dagon.exe
• showHelpers = true/false
• indicators to help find clickable spots (for players)
• shotSpots = true/false
• spot region highlighting (for developers)
• showSplash = true/false
• pre-game splash screen
• texCompression = true/false
• speeds up image loading when changing nodes, at the cost of image quality
• texExtension = “tex”, “png”, or “tga”
• extension used when hunting for node image files (defaults to bundled .tex files)
• bundleEnabled = true/false
• set to false to use individual node texture images
• verticalSync = true/false
• limits screen update rate to (usually) 60 frames/sec. Stops visual glitches.

Table Reference

Tables used by Dagon

• Texture Face {N,S,E,W,U,D}
• Spot Direction {NORTH, EAST, WEST, SOUTH, UP, DOWN, NORTHEAST, SOUTHEAST, NORTHWEST, SOUTHWEST, CURRENT}
• Control Mode {DRAG,FIXED,FREE}
• Events {
• ENTER_NODE...not implemented
• ENTER_ROOM...not implemented
• LEAVE_NODE...not implemented
• LEAVE_ROOM...not implemented
• PRE_RENDER...not implemented???
• POST_RENDER...occurs after every screen graphics update
• is this still good? MOUSE_BUTTON...occurs whenever mouse button is clicked ?
• MOUSE_RIGHT_BUTTON...occurs whenever the right mouse button is clicked
• MOUSE_MOVE....occurs whenever the mouse is moved (watch-me-saturate-my-CPU-mode)
• RESIZE...occurs whenever the display window has been resized
  }
• Color {BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY,
  DARKGRAY, BRIGHTBLUE, BRIGHTGREEN, BRIGHTCYAN, BRIGHTRED,B RIIGHTMAGENTA, YELLOW, WHITE}
• Keyboard Keys {F1,F2, …, F12}....on Windows F10 and F12 seem to have problems
• Fade Speed {SLOWEST,SLOW,FAST,FASTEST}...what are these in seconds?