Ruckingenur Editor - Alpha Build

[Zach Barth]

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} }