4 Overview

Scott Duensing edited this page 2022-07-10 00:23:31 +00:00

Singe uses the Lua programming language for scripting game logic. Lua is fast, lightweight, object-oriented, easy to use, and actually used in the games industry. A tutorial in Lua is beyond the scope of this document. Many excellent tutorials exist on the web and YouTube.

Singe uses an event-driven programming model. What this means is that Singe controls the main "program loop" and is in charge of the order of program execution. Singe automatically handles all the details of decoding and presenting video and audio. It manages controllers, mice, and keyboard input. When Singe needs something game-specific, it calls part of your script.

The most basic Singe script that provides all the existing "callbacks" used by Singe looks like this:

-- Singe Game Skeleton.

-- Load the Singe Framework.
dofile("Singe/Framework.singe")

-- Declare any global variables you need here.

function onControllerMoved(axis, value, which)
  --[[
    Reports which controller axis was moved as well as it's current value.
    (Range: -32768 to 32767)  This is used for analog devices.  Digial input
    is handled by onInput and onKey.
  --]]
end

function onInputPressed(what)
  --[[
    When in keyboard MODE_NORMAL, input events are reported here when the
    key or button is first depressed.  For a full list of keys/buttons/controllers,
    see Singe/Framework.singe.

    For MODE_FULL, this event will be called with the keysym of the key pressed.
  --]]
end

function onInputReleased(what)
  --[[
    When in keyboard MODE_NORMAL, input events are reported here when the
    key or button is released.  For a full list of keys/buttons/controllers,
    see Singe/Framework.singe.

    For MODE_FULL, this event will be called with the keysym of the key released.
  --]]
end

function onKeyPressed(key, scancode)
  --[[
    When in keyboard MODE_FULL, input events are reported here when the key is
    pressed.  Both the keysym and scancode are returned.  For a list of available
    scancodes, see Singe/Framework.singe.
  --]]
end

function onKeyReleased(key, scancode)
  --[[
    When in keyboard MODE_FULL, input events are reported here when the key is
    released.  Both the keysym and scancode are returned.  For a list of available
    scancodes, see Singe/Framework.singe.
  --]]
end

function onMouseMoved(x, y, xr, yr, which)
  --[[
    Called when the mouse is moved.
    When in SINGLE_MOUSE mode, absolute X & Y values as well as the
    relative change in position is returned.  For MANY_MOUSE mode, only
    the relative change is available as well as which mouse was moved.
  --]]
end

function onOverlayUpdate()
  --[[
    This is the only place you can safely perform drawing operations!
    If you wish to display a targeting cursor, you will need to save the
    mouse position from onMouseMoved in global variables and then use those
    here to render the cursor.
  --]]

  -- Tell Singe if we changed the display or not. 
  return(OVERLAY_UPDATED)  -- Or OVERLAY_NOT_UPDATED if no drawing was done.
end

function onShutdown()
  -- Called when the user exits your game.  Free loaded resources here.
end

function onSoundCompleted(id)
  -- The sound "id" just finished playing.
end

-- Note:  There is no "onStartup" event.
--        Any startup code you need can be placed here.