The first weblog devoted to Demoniak3D Demo-System

LUA programming tips & tools

November 28th, 2007 Posted in Demoniak3D, Lua, Programming, Tips'n'Tricks

Developing LUA code for Hyperion can be somewhat frustrating if you don’t follow some guidelines to code, test and debug before launching it in Hyperion. Here is how I work:

  1. I extensively use LuaEdit. LuaEdit is a complete IDE for LUA that offers an editor with syntax coloring and auto completion, syntax checking, plus a complete debugger with step by step, breakpoints and variables watch. It also includes some project management features, alas still a bit unstable. It’s the best IDE I found for LUA, and it’s free : get it !
  2. I write my code in order to test it as much as possible outside Hyperion. The trick is to have a variable set to true if the code runs in Hyperion and false otherwise. Either I include
    hyperion = true

    in my script, or I put something like

    if HYP_GetBaseDir then hyperion=true end

    somewhere at the beginning of my code to detect if any Hyperion API function is defined.

  3. Then I use the “hyperion” variable to alter the execution of low-level functions. A quite important function to define this way is
    function require(file)
        if hyperion then
            dofile(HYP_GetBaseDir()..file)
        else
            dofile(file)
        end
    end

    which ensures files are included the same way in Hyperion or outside it.(*)

  4. LUA allows to define functions twice and “instantiate” only one. For example, one could also have written :
    if hyperion then
        function require(file)
            dofile(HYP_GetBaseDir()..file)
        end
    else
        function require(file)
            dofile(file)
        end
    end

    This is useful for performance critical functions, or to clearly distinguish test code from Hyperion code

  5. Another useful trick is to define:
    function log(s)
        if hyperion then HYP_Debug.Trace(s) else print(s) end
    end

    this enables easy tracing whether in Hyperion or not

  6. Of course it’s not possible to test a complex interactive graphics application outside Hyperion, but most functions can be tested by creating “unit testing” modules, which can fool the tested code by emulating the required Hyperion API. For example :
    -- this is the function that must be tested:
    function IsLeftOf(id1,id2)
        local x1,y1,z1 = HYP_Object.GetPosition(id1)
        local x2,y2,z2 = HYP_Object.GetPosition(id12)
        if x1<x2 then return true else return false end
    end
    
    -- this is the test code
    -- emulate the Hyperion API functions we need
    HYP_Object={}
    HYP_Object.GetPosition = function(id) return id,4,5 end
    
    assert(IsLeftOf(1,2))

Using the tricks above, I’m able to run, test and debug 90% of my code in LuaEdit, before launching it in Hyperion. This saves me a lot of time and hopefully will lead to reliable libs that you’ll be able to use very soon.

(*) Note : Hyperion doesn’t support the standard “require” LUA function, which ensures a file is included only once. By redefining it, we reach 2 goals :

  1. by using dofile(), an included file is read the same number of times either in Hyperion or outside of it,
  2. when JegX will implement “require” in Hyperion, we’ll only have to remove the function.

You must be logged in to post a comment.