Lua Edu Tools - How to add your own feature [Tutorial]

[Vincent]

The cockpit overlay feature was not added to the Lua Edu Tools because it is not directly related to an educational purpose. However, I think that providing a short tutorial that describes how to add an overlay texture (cockpit, keychart, worksheet, ...) might be quite interesting for users who want to learn how to customize the Lua Tools.

So here's a first example that explains how to add the cockpit overlay feature. The changes should be trivial if you wish to add a keychart overlay texture instead...

1- First, we build a new 'cockpitBox.lua' file: open a new text file and save it as 'cockpitBox.lua' in the 'tools' folder.
Here's how we build the code in the cockpitBox.lua file:
- The following line defines the required file for translations:

Code: Select all

require "locale";


- Then, we add a cockpitBox to the toolBox:

Code: Select all

----------------------------------------------
-- Set up and Draw the boxes
----------------------------------------------
cockpitBox = CXBox:new()
   :init(0, 0, 0, 0)
   :movable(false)
   :attach(screenBox, width, height, 0, 0);

cockpitBox.Customdraw =
   function(this)
      textlayout:setfont(normalfont);
      textlayout:setfontcolor(ctext);
      textlayout:setpos(this.lb+25, this.tb-14);
      textlayout:println(_("Cockpit"));
   end;

- Now, let's add the cockpit checkBox to the cockpitBox:

Code: Select all

cockpitCheck = CXBox:new()
      :init(0, 0, 0, 0)
      :bordercolor(cbubordoff)
      :textfont(normalfont)
      :textcolor(cbutextoff)
      :textpos("center")
      :movetext(0, 9)
      :text("")
      :movable(false)
      :active(true)
      :attach(cockpitBox, 100, 4, 35, 5)

cockpitCheck.Action = (function()
   return
      function()
         cockpitFrame.Visible = not(cockpitFrame.Visible);
         if cockpitFrame.Visible then
            cockpitCheck.Text = "x";
         else
            cockpitCheck.Text = "";
         end
      end
   end) ();

- We finally set up the cockpit Frame that holds the cockpit texture:

Code: Select all

cockpitFrame = CXBox:new()
   :init(0, 0, 0, 0)
   :fillimage(celestia:loadtexture(cockpitTexture))
   :movable(false)
   :active(false)
   :visible(false)
   :clickable(true)
   :attach(screenBox, 0, 0, 0, 0)

NB: The attach field takes 5 arguments: attach(parent, lb, bb rb, tb) where parent is the parent box and lb, bb, rb, tb are the distances in pixels respectively to the left, bottom, right, and top borders of the parent box.

2- Then, we must precise the height of the cockpitBox in the toolbox definition:
- Open the 'utils/toolBox.lua' file
- Add the following line to the boxheight definition:

Code: Select all

boxheight =
   {
      timeBoxH = 98,
      lightBoxH = 43,
      magnitudeBoxH = 43,
      galaxyLightBoxH = 43,
      renderBoxH = 22,
      obsModeBoxH = 135,
      solarSystemBoxH = 22,
      fovBoxH = 43,
      asteroidBeltBoxH = 20,
      infoBoxH = 20,
      measureBoxH = 20,
      distanceBoxH = 20,
      magnificationBoxH = 20,
      virtualPadBoxH = 20,
      cockpitBoxH = 20,   -- <== Line to add
      compassBoxH = 20
   }

3- We must also edit the config.lua file:
- Add the cockpitBox to the toolset:

Code: Select all

toolset =
   {
      "timeBox",
      "lightBox",
      "magnitudeBox",
      "galaxyLightBox",
      "renderBox",
      "obsModeBox",
      "solarSystemBox",
      "fovBox",
      "asteroidBeltBox",
      "infoBox",
      --"measureBox",
      "distanceBox",
      "magnificationBox",
      "virtualPadBox",
      "cockpitBox",   -- <== Line to add
      "compassBox",
   }

- Add the following entry that defines the texture to use for the cockpit overlay:

Code: Select all

-------------------------------------------------------------------------------------------------------
-- Define the texture to use for the cockpit overlay.
-------------------------------------------------------------------------------------------------------
cockpitTexture = "../images/cockpit.png"

4- Finally, we just place our cockpit texture in the 'images' folder.
Here's an example of cockpit texture:


Enjoy!

PS: I voluntarily kept this first example quite simple. However, some of you might be interested in getting further information about some specific parts of the code I've provided. If this is the case, well, just ask, and I'll be happy to provide some further explanations...

[fsgregs]

Vincent:

Thank you for your excellent tutorial. Although I am staring at it with quite a bit of ignorance (I know nothing about LUA coding), I can say that the overlay feature works perfectly when following your directions.

There is one thing I noticed, however. The cockpit overlay covers the text of the screen toolbox where it overlaps. Is there a way to place the overlay behind the toolbox text so the toolbox is always on top?


One other question. Is there a way to turn on the cockpit with a keystroke as well as clicking in the onscreen toolkit box?

FYI, here is a scene with the cockpit overlay activated:



Thanks

Frank

[fsgregs]

Vincent:

I have discovered a serious bug in the cockpit overlay lua script. When the overlay is displayed, I can no longer select anything by left-clicking on the screen. I can not even select any of the lua controls on the lua screen interface.

Perhaps the cockpit is being displayed in front of everything else, and Celestia thinks we are clicking on its window in the foreground instead of what is behind it in space.

That makes the cockpit overlay unusable. Is there a way to correct it?

Frank

[Vincent]

There is one thing I noticed, however. The cockpit overlay covers the text of the screen toolbox where it overlaps. Is there a way to place the overlay behind the toolbox text so the toolbox is always on top?

Frank,

You're right, the toolBox should be always drawn on top. To fix that, you just need to add the following line to the utils/screenBox.lua file (line 43):

Code: Select all

   for k,v in ipairs(toolset) do
      if pcall( function() require (v) end ) then
         local boxH = boxheight[v.."H"];
         local boxT = boxtop[v];
         _G[v]:attach(screenBox, width-boxWidth-2, height-boxH-boxT, 2, boxT);
         _G[v]:orderfront();    -- <== Line to add
      end
   end

I'll make this change to the Lua Edu Tools v1.1.

One other question. Is there a way to turn on the cockpit with a keystroke as well as clicking in the onscreen toolkit box?

Yes, just add this line to your tools/cockpitBox.lua file:

Code: Select all

keymap["C"] = cockpitCheck.Action;

Of course, you can replace "C" (shift+c) with any keystroke of your choice.

I have discovered a serious bug in the cockpit overlay lua script. When the overlay is displayed, I can no longer select anything by left-clicking on the screen. I can not even select any of the lua controls on the lua screen interface.

Perhaps the cockpit is being displayed in front of everything else, and Celestia thinks we are clicking on its window in the foreground instead of what is behind it in space.

That makes the cockpit overlay unusable. Is there a way to correct it?

Again, yes. I forgot to make the cockpitFrame clickable. To fix that, just add the following line to your cockpitFrame definition, in the tools/cockpitBox.lua file:

Code: Select all

cockpitFrame = CXBox:new()
   :init(0, 0, 0, 0)
   :fillimage(celestia:loadtexture(cockpitTexture))
   :movable(false)
   :active(false)
   :visible(false)
   :clickable(true)    -- <== Line to add
   :attach(screenBox, 0, 0, 0, 0)

I've edited my tutorial to add this modification.

[fsgregs]

Vincent:

I sure wish I had your knowledge of Lua. Perhaps when I retire, I can learn it. Your fixes all worked great. Thanks

Question: In the future, if I want to keymap a function key such as f8 or f9, what do I type in the Lua line? Typing "f9" does not seem to work.

Thanks

Frank

[chris]

Vincent:

I sure wish I had your knowledge of Lua. Perhaps when I retire, I can learn it. Your fixes all worked great. Thanks

Question: In the future, if I want to keymap a function key such as f8 or f9, what do I type in the Lua line? Typing "f9" does not seem to work.

That's a current limitation of Lua keyboard handling. We'll have to add support for special keys such as the function keys, arrow keys, etc.

--Chris

[ANDREA]

The cockpit overlay feature was not added to the Lua Edu Tools because it is not directly related to an educational purpose. However, I think that providing a short tutorial that describes how to add an overlay texture (cockpit, keychart, worksheet, ...) might be quite interesting for users who want to learn how to customize the Lua Tools. Enjoy!
PS: I voluntarily kept this first example quite simple. However, some of you might be interested in getting further information about some specific parts of the code I've provided. If this is the case, well, just ask, and I'll be happy to provide some further explanations...

Sorry, Vincent, but my own definition of "quite simple" is very different from your one.
Seriously speaking, have you any will to release for Celestia 1.6 a patch enabling the same possibilities of your wonderful celestia_1.4.1_patch3.exe?
I mean something that could ben be easily applied to cel scripts, without the mess of LUA wording that's needed by celx?
I ask this because, after many (believe me, many!) tries to understand the LUA philosophy, I found it absolutely out of my poor brain capabilities, so I hold from trying any more.
But I'm sure that I'm not the only one with this problem so... Vincent, could you make a patch that could allow us to have sound and images using cel scripts under 1.6?
Please!
But, whatever will be your reply, thanks a lot for all what you have done, you are doing now and you will do in the next future, Vincent, always very appreciated.
Bye

Andrea

[BobHegwood]

I ask this because, after many (believe me, many!) tries to understand the LUA philosophy, I found it absolutely out of my poor brain capabilities, so I hold from trying any more.
But I'm sure that I'm not the only one with this problem so... Vincent, could you make a patch that could allow us to have sound and images using cel scripts under 1.6?
Please!

You can add my name to Andrea's here. There is apparently something also inside my particular brain cells which simply says
"To Hell with this..." when it encounters anything to do with Lua, or CELX. Dunno why, but I still cannot get a handle on this stuff.

[ANDREA]

I ask this because, after many (believe me, many!) tries to understand the LUA philosophy, I found it absolutely out of my poor brain capabilities, so I hold from trying any more.
But I'm sure that I'm not the only one with this problem so... Vincent, could you make a patch that could allow us to have sound and images using cel scripts under 1.6?
Please!

You can add my name to Andrea's here. There is apparently something also inside my particular brain cells which simply says
"To Hell with this..." when it encounters anything to do with Lua, or CELX. Dunno why, but I still cannot get a handle on this stuff.

So, Bob, now you are no more the lone Brain-Dead in Celestia community, heeheehee!
Bye

Andrea

[ANDREA]

Vincent, I fear that your LUA EDU TOOLS don't work in Fridger's new r4446, but may be I made some installation mistake with them.
Could you please kindly check if the problem is only mine?
Bye

Andrea

[Vincent]

Vincent, I fear that your LUA EDU TOOLS don't work in Fridger's new r4446, but may be I made some installation mistake with them.
Could you please kindly chcek if the problem is only mine?

Andrea,

Everything is OK for me...
Of course, the Lua Tools don't include the new classes of object (dwarf planet, minor moon, globulars,...) yet.
That will be adressed in the next version that I will (probably) release when Celestia 1.6 is out.

I think your problem may come from the celestia.cfg file, which was concerned by Fridger's changes.
Did you add the following line?

Code: Select all

LuaHook "luahookinit.lua"

Did you also paste a copy of the luahookinit.lua file in your celestia base folder?

[ANDREA]

Vincent, I fear that your LUA EDU TOOLS don't work in Fridger's new r4446, but may be I made some installation mistake with them.
Could you please kindly chcek if the problem is only mine?

Andrea, I think your problem may come from the celestia.cfg file, which was concerned by Fridger's changes. Did you add the following line?

Code: Select all

LuaHook "luahookinit.lua"

Did you also paste a copy of the luahookinit.lua file in your celestia base folder?

Damn...!
I pasted it the r4445 installation, but I forgot to do the same on the r4446.
Sorry for the stupid problem, shame on me.
Bye and thank you.

Andrea