Celestia/Celx Scripting/CELX Lua Methods/Callback

Keyboard
boolean

The callback for keyboard input must have the name "celestia_keyboard_callback". After a script activates the handling keyboard-input by calling celestia:requestkeyboard(true) (see celestia:requestkeyboard), any keypress will result in a call to a method with this name. The callback can return either true or false, indicating that it either has handled the keypress or that Celestia should continue normal processing for this key. Not returning any value is the same as returning true.

Notes:
 * 1) Some special keys like the cursor-keys or [Esc] key won't activate the callback.
 * 2) If an error occurs while processing the callback, the error message will be written to the console log (made visible with the tilde [~] key on the keyboard, or [~] + [Spacebar] on some systems) and an implicit false is returned, i.e. Celestia will continue processing for this key.

Example: The following example code can be used to run some specific CELX code when the user presses the [1] or [2] key on the keyboard.

-- Initialize variable to have no content: last_pressed_key = nil -- Define functions section: function celestia_keyboard_callback(key) last_pressed_key = key return true end function get_pressed_key last_pressed_key = nil celestia:requestkeyboard(true) while true do      if last_pressed_key ~= nil then key = last_pressed_key last_pressed_key = nil celestia:requestkeyboard(false) return key end wait(0.1) end end -- Main CELX script section: -- Section within your script, where you want to handle keyboard input: key = get_pressed_key if key == "1" then valid_key = true celestia:print("Pressed the [1] key", 5.0, -1, -1, 2, 4) wait(5.0) -- You can add more CELX code here, specific to the [1] key elseif key == "2" then valid_key = true celestia:print("Pressed the [2] key", 5.0, -1, -1, 2, 4) wait(5.0) -- You can add more CELX code here, specific to the [2] key else valid_key = false celestia:print("Pressed invalid key", 5.0, -1, -1, 2, 4) wait(0.1) end if valid_key then celestia:print("The [1] and [2] keys are valid keys", 5.0, -1, -1, 2, 4) wait(5.0) -- You can add more CELX code here, specific to both the [1] and [2] keys end

Cleanup
Whenever a Lua script terminates (because it ended, the user terminated it by pressing the [Esc] key or an error occurred), Celestia will try to execute a function with the name "celestia_cleanup_callback".

This function can be used to perform any cleanup actions, notably restoring settings to the values in use before the script started. Within a CELX script, many Celestia options can be set that differ from the standard settings of a user. By using this Cleanup callback function, settings can be reset to the way they were before running the script.

The use of this Cleanup function is essential to program your CELX scripts user friendly !

Notes:
 * 1) Errors will only be reported in the console log (made visible with the tilde [~] key on the keyboard, or [~] + [Spacebar] on some systems).

Example: The following example code can standard be inserted at the beginning of any CELX script (using Celestia version or later), to restore the Celestia settings to the way they were before running the script and to initialize those setting to the way you like them within your CELX script.

Note: When using older Celestia versions, watch the comments in the example to remove some code, so the example also works with Celestia version, version 1.5.1 and version.

-- Define Cleanup function to restore the settings -- to the way they before running the script. function celestia_cleanup_callback celestia:setrenderflags(orig_renderflags) celestia:setlabelflags(orig_labelflags) celestia:setorbitflags(orig_orbitflags) celestia:setambient(orig_amb) celestia:setfaintestvisible(orig_faintest) celestia:setminorbitsize(orig_minorbit) celestia:setstardistancelimit(orig_stardistance) celestia:setminfeaturesize(orig_minfeature) celestia:setstarstyle(orig_starstyle) celestia:settime(orig_time + (celestia:getscripttime / 24 / 3600) ) celestia:settimescale(orig_timescale) celestia:setgalaxylightgain(orig_galaxylight) celestia:getobserver:setfov(orig_fov) celestia:getobserver:setlocationflags(orig_locationflags) celestia:getobserver:singleview celestia:setoverlayelements(orig_overlay) celestia:setaltazimuthmode(orig_altazimuthmode) -- Comment next line if NOT using Celestia v1.6.0 or later celestia:settextureresolution(orig_textres) -- Comment next line if NOT using Celestia v1.6.1 or later celestia:settextcolor(orig_txt_r,orig_txt_g,orig_txt_b) end -- immidiatily followed by the following code to obtain the -- current user settings and save them during the script. orig_renderflags                = celestia:getrenderflags orig_labelflags                 = celestia:getlabelflags orig_orbitflags                 = celestia:getorbitflags orig_amb                        = celestia:getambient orig_faintest                   = celestia:getfaintestvisible orig_minorbit                   = celestia:getminorbitsize orig_stardistance               = celestia:getstardistancelimit orig_minfeature                 = celestia:getminfeaturesize orig_starstyle                  = celestia:getstarstyle orig_time                       = celestia:gettime orig_timescale                  = celestia:gettimescale orig_galaxylight                = celestia:getgalaxylightgain orig_fov                        = celestia:getobserver:getfov orig_locationflags              = celestia:getobserver:getlocationflags orig_overlay                    = celestia:getoverlayelements orig_altazimuthmode             = celestia:getaltazimuthmode -- Comment next line if NOT using Celestia v1.6.0 or later orig_textres                    = celestia:gettextureresolution -- Comment next line if NOT using Celestia v1.6.1 or later orig_txt_r,orig_txt_g,orig_txt_b = celestia:gettextcolor -- The following initialization part can be customized -- by the wishes of the CELX writer to the way he/she -- wants the settings to be during the script. celestia:setorbitflags{Planet = true, Moon = false, Asteroid = false, Comet = false, Spacecraft = false, Invisible = false, Unknown = false, DwarfPlanet = false,    -- Comment line if NOT using Celestia v1.6.0 or later MinorMoon = false,      -- Comment line if NOT using Celestia v1.6.0 or later Star = false            -- Comment line if NOT using Celestia v1.6.0 or later } celestia:setrenderflags{atmospheres = true, automag = true, boundaries = false, cloudmaps = true, cloudshadows = true, comettails = true, constellations = false, eclipseshadows = true, galaxies = true, grid = false, markers = false, nebulae = false, nightmaps = true, orbits = false, planets = true, ringshadows = true, stars = true, smoothlines = true, lightdelay = false, partialtrajectories = false, ecliptic = false,      -- Comment line if NOT using Celestia v1.6.0 or later equatorialgrid = false, -- Comment line if NOT using Celestia v1.6.0 or later galacticgrid = false,  -- Comment line if NOT using Celestia v1.6.0 or later eclipticgrid = false,  -- Comment line if NOT using Celestia v1.6.0 or later horizontalgrid = false -- Comment line if NOT using Celestia v1.6.0 or later } celestia:setlabelflags{planets = false, moons = false, spacecraft = false, asteroids = false, comets = false, stars = false, galaxies = false, locations = false, constellations = false, i18nconstellations = false, openclusters = false, nebulae = false, dwarfplanets = false,   -- Comment line if NOT using Celestia v1.6.0 or later minormoons = false,     -- Comment line if NOT using Celestia v1.6.0 or later globulars = false       -- Comment line if NOT using Celestia v1.6.0 or later } celestia:setambient(0.05) celestia:setfaintestvisible(7) -- Make your standard Star Style choice below by -- commenting/uncommenting one of the following lines: celestia:setstarstyle("point") -- celestia:setstarstyle("fuzzy") -- celestia:setstarstyle("disc") -- End of initialization part of the script