Hey everyone,

The first alpha build of the Ruckingenur Editor is finished! You can
download it at the following address:

http://www.zachtronicsindustries.com/RuckingenurEditor-alpha.zip

The controls are pretty straight forward; the only special function is that
you can hold down shift while dragging a circuit board, chip, or project box
to drag everything on top of it with it.

When you run a level, the Ruckingenur Player looks for a file called
script.lua in the same directory as the .ruck file. The
scripting documentation follows at the end of this message.

Any external files, such as sounds or images, should be referenced with a
local filename. Thus, if you wanted to play a file alarm.wav, you would
place it in the same directory as your .ruck file and use the Lua command
API_PlaySound("alarm.wav"). Same goes for images.

If you have any questions or problems, let me know. This is an alpha build;
while everything *should* work, not everything *does* work. I've rebuilt
level 1 from Ruckingenur II using the editor; you can find it in the
level1-remake folder.

- Zach

  Level Interface - Data Structures

   - PULSESTATE
    - Designates the pulse state at a point.
      - Integer value.
      - PULSESTATE_NONE = 0
      - PULSESTATE_LOW = 1
      - PULSESTATE_HIGH = 2
      - REGISTERLIST
    - Designates a set of registers.
      - Is returned by RUCK_ReadDebug to read from a debug pin on a chip.
      - Consists of a Lua table with 0 to 4 REGISTERs. Note that Lua array
      indicies start at 1, not 0.
      - REGACCESS
    - Designates the read/write status of a register.
      - Integer value.
      - REGACCESS_READ = 0
      - REGACCESS_WRITE = 1
      - REGACCESS_READWRITE = 2
      - REGISTER
    - Designates a register.
      - Consists of a Lua table with three named fields:
       - name: (String) The name of the register.
         - value: (String) An eight character string containing only the
         digits 0-9 and uppercase letters A-F.
         - access: (REGACCESS) The read/write access for the register.

Level Interface - Implemented by Level Designer

   - float LEVEL_ReadVoltage(int pointId)
    - Should return the voltage to be read at a specific point.
      - Called every cycle.
      - void LEVEL_SetPulse(int pointId, PULSESTATE pulseState)
    - Called every cycle with the pulse value at a test point.
      - REGISTERLIST RUCK_ReadDebug(int pointId)
    - Should return the debug status when connected to a test point.
      - Should return nil if test point is not a debug point.
      - Called every cycle.
      - void LEVEL_WriteDebug(int pointId, int registerIndex, string
   registerValue)
    - Called when the user writes a value to a register.
      - registerValue is a valid REGISTER value (see REGISTER definition).
      - registerIndex is a valid index into a REGISTERLIST (see REGISTERLIST
      definition).
      - void LEVEL_WriteSerial(int pointId, string serialData)
    - Called when the user writes a serial character to a pin.
      - serialData is a single character, uppercase string.
      - void LEVEL_Update(float timeDelta)
    - Called every cycle.
      - timeData contains the time, in floating point seconds, since Update
      was last called.
      - void LEVEL_WidgetEvent(string widgetName, string eventName)
    - Called when the player uses a widget (such as pushing a button).
      - widgetName is the name assigned by the player to the widget.
      - actionName is the action string associated with the action
      performed.
      - void LEVEL_TimerCallback(string timerName)
    - Called when a timer created using API_SetTimer triggers.
      - timerName is the string provided when creating the timer.

Level Interface - Functions Callable by Level Code (Engine API)

   - void API_EmitSerial(int pointId, string serialData)
    - If the serial probe is on the test point specified by pointId when
      this function is called, the text in serialData will be echoed
to the serial
      interface screen. Data is buffered by the engine to create an artificial
      delay, causing the text to appear to be pushed to the hypermeter
screen with
      a brief delay between characters.
      - serialData can be a string of any length and may contain any valid
      characters. It should be noted that the player is only able to send
      uppercase characters, one at a time, via the serial device.
      - void API_LevelWin()
    - Causes the player to win the level.
      - void API_LevelLose()
    - Causes the player to lose the level.
      - void API_ShowDatasheet(string datasheetImageFilename)
    - Displays the file specified in datasheetImageFilename in the datasheet
      window of the hypermeter.
      - This is called automatically for ICs and other standard parts with
      the Datasheet property defined.
      - object API_WidgetGet(string widgetName, string propertyName)
    - Returns the value of a property of the widget with name widgetName.
      - Only supports properties listed in "Script Properties" section of
      the level editor for a selected object (i.e. "enabled" for an
LED, but not
      "X" or "DisplayLevel").
      - void API_WidgetSet(string widgetName, string propertyName, object
   propertyValue)
    - Sets the value of a property of the widget with widgetName.
      - Only supports properties listed in "Script Properties" section of
      the level editor for a selected object (i.e. "enabled" for an
LED, but not
      "X" or "DisplayLevel").
      - void API_SetTimer(string timerName, float duration, bool repeating)
    - Creates a timer with the provided name, duration (in floating-point
      seconds), and whether the timer should repeat.
      - Calling API_SetTimer with a duration of 0 will cancel a timer.
      - void API_PlaySound(string soundName)
    - Plays a sound from your level directory. Full filename (i.e.
      "unlock.wav").
      - You may also play the following built-in sounds: "_error", "_beep",
      "_chirp", "_button", "_switch"

Framework Level

function LEVEL_ReadVoltage(pointId)
        -- This function should return the current voltage at a test point.
        return 0
end

function LEVEL_SetPulse(pointId, pulseState)
        -- This function is called every cycle, once for each test point,
with the current pulse state.
end

function LEVEL_ReadDebug(pointId)
        -- This function should return a REGISTERLIST with the current debug
information at a test point.
        -- This function should return nil if the test point is not debug enabled.
        return nil
end

function LEVEL_WriteDebug(pointId, registerIndex, registerValue)
        -- This function is called when the player writes a value to a
register. Register index starts at 0 for the first register.
end

function LEVEL_WriteSerial(pointId, serialData)
        -- This function is called when the player sends a character over the
serial interface to a test point.
end

function LEVEL_Update(timeDelta)
        -- This function is called every cycle with the time, in
floating-point seconds, since LEVEL_Update was last called.
end

function LEVEL_WidgetEvent(widgetName, eventName)
        -- This function is called every time a widget event fires.
end

function LEVEL_TimerCallback(timerName)
        -- This function is called when a timer, set with API_SetTimer, fires.
end

Creating Registers

RL_KeypadChip = {{name="ERROR", value="00000000", access=REGACCESS_READ}}

RL_LockChip = { {name="KEYCODE", value="01030904", access=REGACCESS_READ},
                {name="KEYSWAP", value="0F0F0F0F", access=REGACCESS_READ},
                {name="ERROR", value="00000000", access=REGACCESS_READ} }