[WIP] Rough draft of Spring Lua Guide

[tombom]

simulation = the game

[smoth]

FFFFFFFFFFFFFFFFFFffffff

[slogic]

simulation = the game

right, i should read below about the sim.

[SpliFF]

Yes simulation. It's the game world and it's always the same on every computer in the same game, as distinct from UI stuff which players can change. Gadgets actually run both Synced (in the Sim) and Unsynced (in the UI layer) so one gadget can actually change both environments.

[danuker]

Congratulations for your work! Keep going! This will help the Spring community very much!

[slogic]

widget:Update() has one argument (in LuaUI v0.3) which is equal to Spring.GetLastUpdateSeconds(). gadget:Update() implementation depends on the mod. Currently in CA & BA it does not have an argument.

PS. A question to author. Is document update upcoming or not? This document is a key document & updating is very important. Looks like you left many TODO stuff there.

[SpliFF]

Yes updates are coming to this manual and my Mod Creation manual. The slow pace is because I document things as I'm learning them which pretty much limits the speed of updates to the amount of time I'm implementing new features in my mod.

In the last 4 months I've spent most of my available time on units, texturing and models which are topics covered by the other manual but not the Lua Guide. I only have one Lua widget atm and it's just there to spawn test units. When I start work on the automation, setup and scoring systems I will have a lot more to contribute to the Lua Guide.

Once my mod is in beta I'll spend some time going over the wiki and forums to pull in stuff I've missed. For now this manual is best considered an addendum to those resources.

Don't worry, I'm writing a game that has been in my head for nearly 10 years. Just like Spring it is a long-term project and short of any accident I will be around for a long time to get this manual up to scratch.

For people wanting to contribute to these manuals the best way is still via the wiki as I refer to it often.

UPDATE: I'm taking on a fairly ambitious project to update Springs model loading system. I won't have time to update this for some time. It isn't abandoned though, just downgraded on my priorities list. Feed the wiki.

[maximinus]

Where do you put the new widgets? I'm following the guide and on page 5 is says to try the bare-bones script in Spring/LuaUI/Widgets/test.lua. As I'm on Linux I've put it into ~/.spring/LuaUI/Widgets/test.lua (and also tried /usr/share/games/spring/LuaUI/Widgets/test.lua) and it fails to show up.

Edit: I managed to fiddle enough with the file ~/.spring/LuaUI/Config/BA.lua - BA is the only mod I have right now - to make it work (but not appear when I press F11). But I'm not really sure I know what I'm doing. Is there a canaconical place to put a widget and make it appear all the team to make testing easy?

[SpliFF]

As far as I can see there is no problem with the instructions in the guide or the location you used. Check your infolog.txt for syntax errors in your file, as this is the most likely reason a correctly installed widget would not show up. Also check file/path permissions to see if spring can really read the file/path you're using. Files in LuaUI/Config/ are widget-specific saved options, they should not affect your test widget.

[maximinus]

Here's the output of infolog.txt:

http://pastebin.com/m590a1159

As you can see, there are no errors, nor are there any references to the test.lua script, basically it seem like it's being ignored.

This is annoying since I'm fine with Lua code, and the rest of your guide seems solid, I just need to able to get a first script or widget working and then I can contribute some useful code!

EDIT: F**king slap me with a silly stick and hand in my geek card: just SCROLL DOWN WITH THE MOUSE WHEEL and it's there. Apologies for being such a idiot

[SpliFF]

I just noticed this thread contained the manual as an attachment, rather than pointing to where it lives on my server. That means despite having made several updates since the release many people will have an older version. I recommend anybody who is using this manual follow the link in the first post to grab the latest version. The manual grows organically as I add stuff and re-upload so don't expect me to announce major releases, just re-download every month or so for updates.

Updates as of Nov 2009:
* Detailed info on the new Lua unit scripts (thx to Tobi)
* Section on debugging expanded
* Section on loading/saving widget config data added
* Expanded explanation of VFS (Virtual File System)
* Widget info fields explained
* General tidy-ups and small corrections

[Sausage]

I've been learning abit out lua and the learning the code but this whole 'installing lua' process confuzlez me, according to this book I have to 'choose how to install' and then I have to 'build' it and 'find my systems shell' and theres something about 'the enviroment' and 'enviroment variables' and I have to 'compile lua'. I think it expects me to know all these terms.. I have heard of some of them but I have no idea what I'm doing. pls tell me it sounds harder than it actually is.

[FLOZi]

I've been learning abit out lua and the learning the code but this whole 'installing lua' process confuzlez me, according to this book I have to 'choose how to install' and then I have to 'build' it and 'find my systems shell' and theres something about 'the enviroment' and 'enviroment variables' and I have to 'compile lua'. I think it expects me to know all these terms.. I have heard of some of them but I have no idea what I'm doing. pls tell me it sounds harder than it actually is.

You don't need to install the lua programming language to be able to write lua code which Spring can run.

[AF]

May be of help to noncoders:

http://lua.gts-stolberg.de/en/index.php

[zwzsg]

Oh darn I just linked to it in another thread, unaware of you having already posted it there. Indeed that's the only Lua tutorial I can find that would be useful to someone who's not already a coder. The only cons of that site is that the english has been mangled in translation, the sentences are constructed in a weird way, and that make the text more confusing than it ought to be.

[enetheru]

I've been getting my head around lua and the widget code slowly, and I thought this might smooth the curve for someone like me

If its useful please feel free to include it in the guide under any licence you want with any corrections etc.

Code: Select all

function widget:GetInfo()
  return {
    name      = "GUI_Tut_Hello_World",
    desc      = "Draw a Rectangle and text to the screen",
    author    = "Enetheru",
    date      = "17 June 2010",
    license   = "GPLv2 or later",
    layer     = 1, -- not sure what layer I should be using
    enabled   = false -- default to disabled
  }
end

-- Used to store the view size
local view_w, view_h

-- By localising finction calls it speeds up calling them. in this
-- little program it isnt useful as i only really use the functions once each
-- but in more complex setups where calling them 1000's of times there can be
-- considerable improvement
local gl_GetViewSizes = gl.GetViewSizes
local gl_Color = gl.Color
local gl_Rect = gl.Rect
local gl_Text = gl.Text

-- This function is what is run when you enable the widget, it is only run once.
function widget:Initialize()
        -- Get and store the view size.
        -- gl.GetViewSizez() -> width, height
        view_w, view_h = gl_GetViewSizes()
end

-- This function runs every screen update, so make it really fast..
function widget:DrawScreen()
        -- Draw a rectangle
        -- gl.Color(red, green, blue, alpha) -> nil
        -- RGBA Colour values range from 0.0 to 1.0.
        -- In this case I have gone for dark grey at 50% opacity.
        gl_Color( 0.1, 0.1, 0.1, 0.5 )

        -- gl.Rect( x1, y1, x2, y2) -> nil
        -- Coordinate system starts at 0,0 bottom left.
        -- First two coordinates are the bottom left of the rectangle, second two
        -- are the top right.
        gl_Rect( view_w / 3.0, view_h / 3.0,
                        view_w * 2.0 / 3.0, view_h * 2.0 / 3.0 )

        -- Draw some text
        -- Full white
        gl_Color( 1, 1, 1, 1)

        -- gl.Text("text", x-position, y-position, size [, "options"]) -> nil
        -- where "options" are:
        -- 'c' = center
        -- 'r' = right
        -- 'n' = deactives colorCodes (so you can use gl.Color() to write
        --              transparent text etc.)
        -- 'o' = black outline
        -- 'O' = white outline
        gl_Text( "Hello World!", view_w / 2, view_h / 2, 16, "co" )
end

[Neddie]

Made a PDF of the handler actions and call-ins on one sheet. Credited SpliFF, released into Public Domain.

[0bliter8or]

I Have been investigating Spring AI and widgets for my PhD this widget guide has be a life saver.

I wrote some handy functions while I was poking around to see how things work.
there are some functions for writing tables to files in a human readable form. also included is a function for Echoing small tables and another for testing the parameters of widget call ins as some of them don't seem to match the documentation.

I placed them all in an example widget, feel free to do whatever you like with the code

[Jools]

Great. Will test it sometime. I usually just dump the tables to infolog in widget:shutdown() and use excel macro to format them.

[yanom]

simulation = what's happening in the game. It's a simulation because... idk, go ask an engine developer.