CELX Scripting Documentation

Дата на публикуване:

Quick start: a .celx script runs as a Lua coroutine. Time-blocking is done with wait(seconds); the script can call any of the methods below to manipulate the scene. The top-level objects available at script start are celestia (the simulation), and accessors that fetch others like celestia:getobserver() for the camera.

celestia 136 methods

Top-level scripting object — find/select objects, configure rendering, manage time, audio, and event handlers.

celestia:addimageoverlay(1…10 args)since 0cf8ebe
Append an image overlay without clearing existing ones. Same argument list as overlay(). Returns an id that can be passed to removeimageoverlay().
  • arg 1 duration number seconds default: 3.0 How long the image stays visible.
  • arg 2 xoffset number pixels default: 0 Horizontal pixel offset from the anchor corner.
  • arg 3 yoffset number pixels default: 0 Vertical pixel offset from the anchor corner.
  • arg 4 alpha number | nil 0.0–1.0 Global alpha override applied to all corners. Pass nil to keep each corner's own alpha.
  • arg 5 filename string Image file path. Relative paths resolve against the images/ data folder.
  • arg 6 fitscreen boolean | number default: false When true, scale the image to fill the screen.
  • arg 7 fadeafter number seconds Seconds into the display at which fading begins. Defaults to duration (no fade).
  • arg 8 width number pixels default: 0 Override rendered width. 0 or omitted uses the texture's intrinsic width. Ignored when fitscreen is true.
  • arg 9 height number pixels default: 0 Override rendered height. 0 or omitted uses the texture's intrinsic height. Ignored when fitscreen is true.
  • arg 10 colors table | nil Per-corner color table. Supported keys: color, colortop, colorbottom, colortopleft, colortopright, colorbottomright, colorbottomleft. Values are named colors or "#rrggbb" / "#rrggbbaa" strings.
returns
  • ret 1 number | nil Image id (pass to removeimageoverlay()), or nil if the image could not be loaded.
celestia:bindtranslationdomain()since a2dba1e
Bind a gettext translation domain to a directory containing .mo files. Only effective when Celestia was built with NLS support; otherwise this is a no-op.
  • arg 1 domain string Translation domain name.
  • arg 2 directory string Path to the locale directory containing message catalogs.
returns
  • ret 1 string | nil The resolved directory path bound to the domain, or nil if binding failed or NLS is disabled.
celestia:clearimageoverlays()since 0cf8ebe
Drop every currently-displayed overlay image immediately.
celestia:createcelscript(…)since 1.5.1
Compile a cel-script source string into an executable `celscript` object.
  • arg 1 scripttext string
returns
  • ret 1 celscript
celestia:deletecategory()since e6e84d1
Delete a category (must be empty).
  • arg 1 category_or_name category | string
returns
  • ret 1 boolean
celestia:dsos()since 1.5.1
Iterator over every deep-sky object.
returns
  • ret 1 function Iterator over DSOs.
celestia:find(…)since 1.5.1
Look up an object by hierarchy path (e.g. `"Sol/Earth"`) and return an `object`, or nil if not found.
  • arg 1 path string Hierarchy path, e.g. "Sol/Earth" or a star name.
returns
  • ret 1 object | nil The found object, or nil.
celestia:findcategory()since e6e84d1
Find a category by name.
  • arg 1 name string
returns
  • ret 1 category | nil
celestia:flash(1…2 args)since 1.5.1
Show a transient message that fades out.
  • arg 1 text string Message to flash on-screen.
  • arg 2 duration number seconds default: 1.5 Time the message stays visible. Default 1.5.
celestia:fromjulianday(…)since 1.5.1
Convert a Julian date number to a date table.
  • arg 1 jd number Julian date default: 0 Julian date to decompose.
returns
  • ret 1 table {year, month, day, hour, minute, seconds}.
celestia:getaltazimuthmode()since 1.5.1
Whether alt-azimuth mount mode is enabled.
returns
  • ret 1 boolean
celestia:getambient()since 1.5.1
Get ambient light level.
returns
  • ret 1 number 0.0–1.0
celestia:getcategories()since e6e84d1
List of all categories.
returns
  • ret 1 table
celestia:getdso(…)since 1.5.1
Get a deep-sky object by index in the catalog.
  • arg 1 n integer Zero-based catalog index. Must be less than the value returned by celestia:getdsocount.
returns
  • ret 1 object
celestia:getdsocount()since 1.5.1
Number of DSOs in the catalog.
returns
  • ret 1 integer
celestia:geteventhandler(…)since 1.5.1
Currently-registered handler function for an event.
  • arg 1 event string Event name (e.g. "key", "tick", "mousedown", "mouseup").
returns
  • ret 1 function | nil
celestia:getfaintestam45deg()since 4ac5584
Get the renderer's faintest-magnitude at 45° FOV.
returns
  • ret 1 number magnitude
celestia:getfaintestvisible()since 1.5.1
Get the faintest-visible-magnitude (mode-aware).
returns
  • ret 1 number magnitude
celestia:getfont()since 1.5.1
Get the default screen font.
returns
  • ret 1 font
celestia:getgalaxylightgain()since 1.5.1
Get galaxy brightness gain.
returns
  • ret 1 number 0.0–1.0
celestia:getlabelcolor(…)since 1.6.1
Get the color of a named label class. Returns three numbers (red, green, blue).
  • arg 1 key string Label class name.
returns
  • ret 1 r number 0.0–1.0
  • ret 2 g number 0.0–1.0
  • ret 3 b number 0.0–1.0
celestia:getlabelflags()since 1.5.1
Current label flags.
returns
  • ret 1 table
celestia:getlayoutdirection()since a76e19b
Return `"ltr"` or `"rtl"` (the text layout direction).
returns
  • ret 1 string "ltr" or "rtl".
celestia:getlinecolor(…)since 1.6.1
Get the color of a named line element. Returns three numbers (red, green, blue).
  • arg 1 key string Line element name.
returns
  • ret 1 r number 0.0–1.0
  • ret 2 g number 0.0–1.0
  • ret 3 b number 0.0–1.0
celestia:getminfeaturesize()since 1.5.1
Get minimum on-screen feature size.
returns
  • ret 1 number pixels
celestia:getminorbitsize()since 1.5.1
Get minimum on-screen orbit size.
returns
  • ret 1 number pixels
celestia:getobserver()since 1.5.1
The active observer.
returns
  • ret 1 observer The active observer.
celestia:getobservers()since 1.5.1
List of all observers in the view manager.
returns
  • ret 1 table Array of observers (one per view).
celestia:getorbitflags()since 1.5.1
Current orbit-display flags.
returns
  • ret 1 table
celestia:getoverlayelements()since 1.5.1
Current overlay element settings.
returns
  • ret 1 table
celestia:getparamstring(…)since 1.5.1
Look up a string in `celestia.cfg`'s `configParams` table.
  • arg 1 key string
returns
  • ret 1 string
celestia:getrenderflags()since 1.5.1
Current render flags.
returns
  • ret 1 table {flagname=true/false, ...}.
celestia:getrootcategories()since e6e84d1
List of top-level categories.
returns
  • ret 1 table
celestia:getsafeareainsets()since 47cfe00
Safe-area insets `(left, top, right, bottom)`.
returns
  • ret 1 number pixels left
  • ret 2 number pixels top
  • ret 3 number pixels right
  • ret 4 number pixels bottom
celestia:getscreendimension()since 1.5.1
DPI-independent window dimensions.
returns
  • ret 1 number width (DPI-independent)
  • ret 2 number height (DPI-independent)
celestia:getscreendpi()since 47cfe00
DPI of the active window.
returns
  • ret 1 number DPI
celestia:getscriptpath()since 1.5.1
Absolute path of the running script.
returns
  • ret 1 string
celestia:getscripttime()since 1.5.1
Seconds elapsed since the script started.
returns
  • ret 1 number seconds
celestia:getselection()since 1.5.1
The current selection.
returns
  • ret 1 object The current selection.
celestia:getstar(…)since 1.5.1
Get a star by index in the catalog.
  • arg 1 n integer Zero-based catalog index. Must be less than the value returned by celestia:getstarcount.
returns
  • ret 1 object
celestia:getstarcolor()since 60a75b9
Get the current star color table.
returns
  • ret 1 string One of "blackbody_d65", "enhanced", "sunwhite", "vegawhite".
celestia:getstarcount()since 1.5.1
Number of stars in the catalog.
returns
  • ret 1 integer
celestia:getstardistancelimit()since 1.5.1
Get the star distance limit (light-years).
returns
  • ret 1 number light-years
celestia:getstarstyle()since 1.5.1
Get the current star drawing style.
returns
  • ret 1 string "fuzzy", "point", or "disc".
celestia:getsystemtime()since 1.6.1
System wall-clock time, converted from the host clock to TDB and returned as a Julian date.
returns
  • ret 1 number Julian date (TDB)
celestia:gettextcolor()since 1.6.1
Get the overlay text color. Returns three numbers (red, green, blue).
returns
  • ret 1 r number 0.0–1.0
  • ret 2 g number 0.0–1.0
  • ret 3 b number 0.0–1.0
celestia:gettextureresolution()since 1.6.1
Get the current texture resolution. Returned as the enum value: 0 = lores, 1 = medres, 2 = hires.
returns
  • ret 1 number 0 (lores), 1 (medres), or 2 (hires).
celestia:gettextwidth(…)since 1.5.1
Measure pixel width of a string in the default font.
  • arg 1 s string
returns
  • ret 1 number pixels
celestia:gettime()since 1.5.1
Get the current simulation time as a Julian date.
returns
  • ret 1 number Julian date (TDB)
celestia:gettimescale()since 1.5.1
Get the simulation time multiplier.
returns
  • ret 1 number real-seconds per simulation-second
celestia:gettintsaturation()since 60b7c85
Get saturation of tinted illumination (0.0–1.0).
returns
  • ret 1 number 0.0–1.0
celestia:gettitlefont()since 1.5.1
Get the title (bigger) font used for overlay text.
returns
  • ret 1 font
celestia:geturl(0…1 args)since 1.6.1
Current state as a cel:// URL. Passing an observer scopes the captured view to that observer; otherwise the active observer is used.
  • arg 1 observer observer Optional. Observer whose view to capture. Defaults to the active observer.
returns
  • ret 1 string A cel:// URL.
celestia:getwindowdimension()since e60ddf6
Window dimensions `(width, height)`.
returns
  • ret 1 number pixels width
  • ret 2 number pixels height
celestia:hide(0…999 args)since 1.5.1
Disable one or more render flags by name (varargs).
celestia:hideconstellations(0…1 args)since 1.6.1
Hide constellations. With no argument, hides every constellation; with a table of name strings, hides only the listed ones.
  • arg 1 names table | nil Optional table of constellation name strings. Omit to hide all.
celestia:hidelabel(0…999 args)since 1.5.1
Disable one or more label categories by name (varargs).
celestia:ispaused()since 1.6.1
Whether the simulation is currently paused.
returns
  • ret 1 boolean
celestia:isplayingaudio(…)since 306ef74
Whether a channel is currently playing.
  • arg 1 channel integer Channel index.
returns
  • ret 1 boolean
celestia:istimesynchronized()since 1.6.1
Whether time is synchronized across all observers.
returns
  • ret 1 boolean
celestia:language()since dbf2b11
Active gettext language code (`zh_CN`, `de`, `ja`, …) or `en` when no translation is loaded. Mirrors the value of `_("LANGUAGE")` in the C++ source.
returns
  • ret 1 string Locale code such as "zh_CN", "de", or "en".
celestia:loadfont(…)since 1.5.1
Load a TTF/OTF font, returning a `font` object.
  • arg 1 path string
returns
  • ret 1 font | nil
celestia:loadtexture(1…3 args)since 1.5.1
Load a texture from disk, returning a `texture` object. Optional address mode (`"wrap"`/`"edgeclamp"`/`"borderclamp"`) and mipmap mode (`"default"`/`"none"`).
  • arg 1 path string File path.
  • arg 2 address_mode string since 65c4afd "wrap", "edgeclamp", or "borderclamp". Default "edgeclamp".
  • arg 3 mip_mode string since 65c4afd "default" or "none". Default "default".
returns
  • ret 1 texture | nil
celestia:log(…)since 1.5.1
Print to the system log (clog).
  • arg 1 text string
celestia:mark(…)since 1.5.1
Place a marker (uses simple defaults; for full control use `object:mark`).
  • arg 1 obj object
celestia:newcategory()since e6e84d1
Create a new top-level category.
  • arg 1 name string
returns
  • ret 1 category | nil
celestia:newframe(1…3 args)since 1.5.1
Construct a reference frame: `(coordsys, [refobj], [targetobj])` where `coordsys` is one of `"universal"`, `"ecliptic"`, `"equatorial"`, `"bodyfixed"`, `"observer"`, `"lock"`, `"chase"`.
  • arg 1 coordsys string Coordinate system: "universal", "ecliptic", "equatorial", "bodyfixed", "observer", "lock", or "chase".
  • arg 2 refobj object Primary reference object for the frame.
  • arg 3 targetobj object Secondary object (only used for "lock" frames).
returns
  • ret 1 frame
celestia:newposition(…, …, …)since 1.5.1
Construct a `position` from three components (in micro-light-years, the celx native unit) or three R128 base-64 strings.
returns
  • ret 1 position
celestia:newrotation(2…4 args)since 1.5.1
Construct a quaternion: either `(axis_vec, angle_radians)` or four numbers `(w, x, y, z)`.
  • arg 1 axis_or_w vector | number Either the rotation axis (vector form) or the quaternion w (4-number form).
  • arg 2 angle_or_x number radians (axis form) | unitless (4-number form) Either the rotation angle in radians, or the quaternion x component.
  • arg 3 y number Quaternion y component (4-number form only).
  • arg 4 z number Quaternion z component (4-number form only).
returns
  • ret 1 rotation
celestia:newvector(…, …, …)since 1.5.1
Construct a 3-vector from three numbers.
  • arg 1 x number X component.
  • arg 2 y number Y component.
  • arg 3 z number Z component.
returns
  • ret 1 vector
celestia:overlay(1…10 args)since d149798
Display an image overlay, replacing any currently-shown overlays. Use addimageoverlay if you need to stack multiple images or retain the id for later removal.
  • arg 1 duration number seconds default: 3.0 How long the image stays visible.
  • arg 2 xoffset number pixels default: 0 Horizontal pixel offset from the anchor corner.
  • arg 3 yoffset number pixels default: 0 Vertical pixel offset from the anchor corner.
  • arg 4 alpha number | nil 0.0–1.0 Global alpha override applied to all corners. Pass nil to keep each corner's own alpha.
  • arg 5 filename string Image file path. Relative paths resolve against the images/ data folder.
  • arg 6 fitscreen boolean | number default: false When true, scale the image to fill the screen.
  • arg 7 fadeafter number seconds Seconds into the display at which fading begins. Defaults to duration (no fade). since 0cf8ebe
  • arg 8 width number pixels default: 0 Override rendered width. 0 or omitted uses the texture's intrinsic width. Ignored when fitscreen is true. since 0cf8ebe
  • arg 9 height number pixels default: 0 Override rendered height. 0 or omitted uses the texture's intrinsic height. Ignored when fitscreen is true. since 0cf8ebe
  • arg 10 colors table | nil Per-corner color table. Supported keys: color (all corners), colortop / colorbottom (two corners each), colortopleft, colortopright, colorbottomright, colorbottomleft. Values are named colors or "#rrggbb" / "#rrggbbaa" strings. Missing keys default to white. since 0cf8ebe
celestia:pause(0…1 args)since a2581b7
Pause / unpause simulation time.
returns
  • ret 1 boolean
celestia:pauseaudio(…)since 306ef74
Pause a channel.
  • arg 1 channel integer
celestia:play(2…6 args)since c6de578
Legacy multi-purpose audio call. Prefer `playaudio`.
  • arg 1 channel integer
  • arg 2 number default: 1.0 since 6088291 must be a number (volume)
  • arg 3 number default: 0.0 since 6088291 must be a number (pan)
  • arg 4 number default: 0 since 6088291 must be a number (loop)
  • arg 5 filename string since 6088291 must be a string (filename)
  • arg 6 number default: 0 since 6088291 must be a number (nopause)
celestia:playaudio(2…7 args)since 306ef74
Start playing an audio file on a channel.
  • arg 1 channel integer Channel index (any non-negative integer; 0 is fine).
  • arg 2 filepath string Path to an audio file (mp3/ogg/wav/flac).
  • arg 3 startTime number seconds default: 0 Playback offset from the beginning of the file.
  • arg 4 volume number 0.0–1.0 default: 1.0 Linear volume scalar.
  • arg 5 pan number −1.0 left … +1.0 right default: 0.0 Stereo pan position.
  • arg 6 loop boolean default: false Loop the file when it ends.
  • arg 7 nopause boolean default: false since 4ac5584 If true, the channel keeps playing even when the simulation is paused.
returns
  • ret 1 boolean True if playback started.
celestia:print(1…6 args)since 1.5.1
Print text to the on-screen overlay. `(text, [duration], [horig], [vorig], [hoff], [voff])`.
  • arg 1 text string Message to print.
  • arg 2 duration number seconds default: 1.5 Time the text stays visible.
  • arg 3 horig integer code -1/0/+1 default: -1.0 Horizontal anchor: -1 = right, 0 = center, +1 = left edge.
  • arg 4 vorig integer code -1/0/+1 default: -1.0 Vertical anchor: -1 = top, 0 = center, +1 = bottom edge.
  • arg 5 hoff number pixels default: 0 Horizontal pixel offset from the chosen anchor.
  • arg 6 voff number pixels default: 5.0 Vertical pixel offset from the chosen anchor.
celestia:printatpixel(1…4 args)since 47cfe00
Print text at pixel coordinates (x, y) from the bottom-left of the screen.
  • arg 1 text string Message to print.
  • arg 2 duration number seconds default: 1.5 Time the text stays visible. Negative values reset to 1.5.
  • arg 3 x number pixels default: 0 X coordinate from the bottom-left of the screen.
  • arg 4 y number pixels default: 0 Y coordinate from the bottom-left of the screen.
celestia:registereventhandler(…, …)since 1.5.1
Register a Lua function as an event handler. Pass nil as the handler to clear.
  • arg 1 event string Event name (e.g. "key", "tick", "mousedown", "mouseup").
  • arg 2 handler function | nil Callback function, or nil to remove the handler.
celestia:removeimageoverlay(…)since 0cf8ebe
Drop a single overlay image previously added by overlay() or addimageoverlay().
  • arg 1 id number The id returned by overlay() or addimageoverlay().
returns
  • ret 1 boolean True if an image with that id was found and removed.
celestia:requestkeyboard(…)since 1.5.1
Request or release keyboard input routing to the script. When true, keystrokes are passed to the script's charEntered callback instead of being handled by Celestia; a charEntered global must exist or an error is raised. When false, normal keyboard handling is restored.
  • arg 1 enable boolean true to route keys to the script, false to release.
celestia:requestsystemaccess(0…1 args)since 1.5.1
Request access to Lua's io and os standard libraries (file I/O, OS calls). The host's script access policy determines the outcome: access is granted immediately, denied silently, or a permission prompt is shown to the user.
celestia:resumeaudio(…)since 306ef74
Resume a paused channel.
  • arg 1 channel integer
returns
  • ret 1 boolean
celestia:runscript(…)since 1.6.1
Run an external script file.
  • arg 1 scriptfile string
celestia:seekaudio(…, …)since 306ef74
Seek the channel's current sound to `time` seconds.
  • arg 1 channel integer
  • arg 2 time number seconds Position within the file to seek to.
returns
  • ret 1 boolean
celestia:select(…)since 1.5.1
Make `obj` the simulation's current selection.
  • arg 1 obj object | nil Object to select; nil clears.
celestia:setaltazimuthmode(…)since 1.5.1
Toggle alt-azimuth mount mode for the active observer.
celestia:setambient(…)since 1.5.1
Set ambient light level (0.0–1.0).
  • arg 1 level number 0.0–1.0
celestia:setasterisms(…)since f550ca4
Load an asterisms (constellation) file, replacing the current set.
  • arg 1 path string Path to a Celestia asterisms .dat file.
celestia:setaudioloop(…, …)since 6088291
Set channel loop boolean.
  • arg 1 channel integer
  • arg 2 loop boolean default: false
celestia:setaudionopause(…, …)since 6088291
Set whether the channel ignores spacebar pause.
  • arg 1 channel integer
  • arg 2 nopause boolean default: false
celestia:setaudiopan(…, …)since 6088291
Set channel pan (-1.0 left, 0.0 center, 1.0 right).
  • arg 1 channel integer
  • arg 2 pan number −1.0 … +1.0 default: 0.0
celestia:setaudiovolume(…, …)since 6088291
Set channel volume (0.0–1.0).
  • arg 1 channel integer
  • arg 2 volume number 0.0–1.0 default: 1.0
celestia:setconstellationcolor(3…4 args)since 1.6.1
Set the diagram color for constellations. Without the fourth argument the color is applied to every constellation; with a table of name strings only the listed constellations are recolored.
  • arg 1 r number 0.0–1.0
  • arg 2 g number 0.0–1.0
  • arg 3 b number 0.0–1.0
  • arg 4 names table | nil Optional table of constellation name strings. Omit to recolor all.
celestia:setfaintest(…)since 1.5.1
Set the simulation faintest-visible-magnitude unconditionally, no clamping. Equivalent to the legacy `setvisibilitylimit{}` cel command.
  • arg 1 magnitude number magnitude
celestia:setfaintestam45deg(…)since 4ac5584
Set the renderer's faintest-magnitude at 45° FOV unconditionally, no clamping. Equivalent to the legacy `setfaintestautomag45deg{}` cel command. Works regardless of AutoMag mode, so scripts can prime the value before flipping AutoMag on.
  • arg 1 magnitude number magnitude
celestia:setfaintestvisible(…)since 1.5.1
Set the faintest-visible-magnitude. When AutoMag is on, writes the AM45deg value (clamped 6–12); otherwise writes the simulation's faintest value (clamped 1–15).
  • arg 1 magnitude number magnitude
celestia:setgalaxylightgain(…)since 1.5.1
Set galaxy brightness gain (0.0–1.0).
  • arg 1 gain number 0.0–1.0
celestia:setlabelcolor(…, …, …, …)since 1.5.1
Set the color of a named label class.
  • arg 1 key string Label class name.
  • arg 2 r number 0.0–1.0
  • arg 3 g number 0.0–1.0
  • arg 4 b number 0.0–1.0
celestia:setlabelflags(…)since 1.5.1
Update label flags from a `{labelname=true/false, ...}` table.
returns
  • ret 1 nil
celestia:setlayoutdirection(…)since a76e19b
Override the text layout direction.
  • arg 1 layoutDirection string
celestia:setlinecolor(…, …, …, …)since 1.5.1
Set the color of a named line element.
  • arg 1 name string Line element name (e.g. "EclipticLine").
  • arg 2 r number 0.0–1.0
  • arg 3 g number 0.0–1.0
  • arg 4 b number 0.0–1.0
celestia:setluahook(…)since 1.5.1
Internal: install Lua hook callbacks.
celestia:setminfeaturesize(…)since 1.5.1
Set minimum on-screen feature size in pixels.
  • arg 1 minFeatureSize number pixels
celestia:setminorbitsize(…)since 1.5.1
Set minimum on-screen orbit size in pixels.
  • arg 1 orbitSize number pixels
celestia:setorbitflags(…)since 1.5.1
Update orbit-display flags from a `{bodytype=true/false, ...}` table.
returns
  • ret 1 nil
celestia:setoverlayelements(…)since 1.5.1
Update HUD overlay elements via a `{element=true/false, ...}` table.
returns
  • ret 1 nil
celestia:setrenderflags(…)since 1.5.1
Update render flags from a `{flagname=true/false, ...}` table.
returns
  • ret 1 nil
celestia:setsafeareainsets(…, …, …, …)since 47cfe00
Override the safe-area insets.
  • arg 1 left number pixels default: 0
  • arg 2 top number pixels default: 0
  • arg 3 right number pixels default: 0
  • arg 4 bottom number pixels default: 0
celestia:setscreendpi(…)since 47cfe00
Override the DPI used for layout calculations.
  • arg 1 screenDpi number DPI
celestia:setstarcolor(…)since 60a75b9
Set the star color table.
  • arg 1 table string One of "blackbody_d65", "enhanced", "sunwhite", "vegawhite".
celestia:setstardistancelimit(…)since 1.5.1
Set the maximum distance (in light-years) at which stars are still rendered.
  • arg 1 distance number light-years
celestia:setstarstyle(…)since 1.5.1
Set the star drawing style: `"fuzzy"`, `"point"`, or `"disc"`.
  • arg 1 style string "fuzzy", "point", or "disc".
celestia:settextcolor(…, …, …)since 1.6.1
Set the overlay text color.
  • arg 1 r number 0.0–1.0
  • arg 2 g number 0.0–1.0
  • arg 3 b number 0.0–1.0
celestia:settextureresolution(…)since 1.6.1
Set the active texture resolution. Pass 0 for lores, 1 for medres, or 2 for hires.
  • arg 1 resolution number 0 (lores), 1 (medres), or 2 (hires).
celestia:settime(…)since 1.5.1
Set the simulation time. Argument is a Julian date.
  • arg 1 t number Julian date (TDB) New simulation time.
celestia:settimescale(…)since 1.5.1
Set the simulation time multiplier. `1.0` is real time; negative values run time backwards.
  • arg 1 scale number real-seconds per simulation-second Time multiplier. 1.0 is real time; negative runs time backwards.
celestia:settimeslice(…)since 1.5.1
Internal: set max time slice for the running script before forcing yield.
  • arg 1 timeslice number seconds Per-tick CPU budget for the script.
celestia:settintsaturation(…)since 60b7c85
Set saturation of tinted illumination (0.0–1.0).
  • arg 1 saturation number 0.0–1.0
celestia:seturl(1…2 args)since 1.6.1
Navigate to a cel:// URL describing a saved camera state. The optional observer scopes the navigation to a specific view; otherwise the active observer is used.
  • arg 1 url string A cel:// URL.
  • arg 2 observer observer Optional. Observer whose view to navigate. Defaults to the active observer.
celestia:setwindowbordersvisible(…)since 1.6.1
Show/hide window borders for split views.
  • arg 1 visible boolean default: true
celestia:show(0…999 args)since 1.5.1
Enable one or more render flags by name (varargs).
celestia:showconstellations(0…1 args)since 1.6.1
Show constellations. With no argument, shows every constellation; with a table of name strings, shows only the listed ones.
  • arg 1 names table | nil Optional table of constellation name strings. Omit to show all.
celestia:showlabel(0…999 args)since 1.5.1
Enable one or more label categories by name (varargs).
celestia:stars()since 1.5.1
Iterator over every star in the catalog.
returns
  • ret 1 function Iterator over stars.
celestia:stopaudio(…)since 306ef74
Stop a channel and release its audio resources.
  • arg 1 channel integer
celestia:synchronizetime(…)since 1.6.1
Toggle observer time-synchronization across views.
  • arg 1 sync boolean
celestia:takescreenshot(0…2 args)since 1.5.1
Save a screenshot to the configured script-screenshot directory using the filename pattern screenshot-{tag-}{NNNNNN}.{filetype}.
  • arg 1 filetype string default: "png" File extension/format. Defaults to "png".
  • arg 2 tag string Optional filename tag inserted before the numeric counter. Characters outside [A-Za-z0-9] are replaced with _, and the tag is truncated to 16 characters.
returns
  • ret 1 boolean True if the screenshot was saved successfully.
celestia:tdbtoutc(…)since 1.5.1
Convert a TDB Julian date to UTC.
  • arg 1 jd number Julian date (TDB) default: 0 TDB Julian date to convert.
returns
  • ret 1 table UTC date table.
celestia:tojulianday(1…6 args)since 1.5.1
Convert a date table `{year=…, month=…, day=…, hour=…, minute=…, seconds=…}` to a Julian date number.
  • arg 1 year integer default: 0 Calendar year.
  • arg 2 month integer default: 1 Month, 1–12.
  • arg 3 day integer default: 1 Day of month, 1–31.
  • arg 4 hour integer default: 0 Hour, 0–23.
  • arg 5 minute integer default: 0 Minute, 0–59.
  • arg 6 seconds number seconds default: 0 Seconds, 0.0–59.999.
returns
  • ret 1 number Julian date
celestia:__tostring()since 1.5.1
String-conversion metamethod — invoked implicitly by `tostring(obj)` and `print`.
returns
  • ret 1 string
celestia:unmark(…)since 1.5.1
Remove markers from an object.
  • arg 1 obj object
celestia:unmarkall()since 1.5.1
Remove all markers.
celestia:utctotdb(1…6 args)since 1.5.1
Convert a UTC Julian date to TDB (Barycentric Dynamical Time).
  • arg 1 year integer default: 0 Calendar year.
  • arg 2 month integer default: 1 Month, 1–12.
  • arg 3 day integer default: 1 Day of month, 1–31.
  • arg 4 hour integer default: 0 Hour, 0–23.
  • arg 5 minute integer default: 0 Minute, 0–59.
  • arg 6 seconds number seconds default: 0 Seconds, 0.0–59.999.
returns
  • ret 1 number Julian date (TDB)
celestia:verbosity(…)since d149798
Set or query the diagnostic message verbosity.
  • arg 1 level integer 0–2 default: 2.0 Higher = more verbose.
celestia:version()since a33e249
Celestia version string.
returns
  • ret 1 string
celestia:windowbordersvisible()since 1.6.1
Whether window borders are visible (multi-view).
returns
  • ret 1 boolean

observer 41 methods

Camera operations — navigation, view manipulation, frame selection.

observer:cancelgoto()since 1.5.1
Stop any in-progress goto/center motion immediately.
observer:center(1…2 args)since 1.5.1
`(target, [time])` — translate the camera so `target` is centered.
  • arg 1 target object
  • arg 2 travelTime number seconds default: 5.0
observer:centerorbit(1…2 args)since 1.5.1
Like `center`, but maintain orbit-distance to the target.
  • arg 1 target object
  • arg 2 travelTime number seconds default: 5.0
observer:changeorbitdistance(…)since 4ac5584
Exponential dolly toward (d > 0) or away from (d < 0) the current selection.
  • arg 1 d number exponential factor Positive moves toward the selection, negative moves away. Magnitude = exp factor per call.
observer:chase(…)since 1.5.1
Set frame to chase-centered on `target` (track velocity).
  • arg 1 target object
observer:deleteview()since 1.5.1
Delete a view by index.
observer:__eq(…)since 1.5.1
Equality metamethod — invoked implicitly by `a == b`.
returns
  • ret 1 boolean
observer:follow(…)since 1.5.1
Set frame to ecliptical-centered on `target`.
  • arg 1 target object
observer:getfov()since 1.5.1
Get the field of view.
returns
  • ret 1 number radians
observer:getframe()since 1.5.1
The observer's current frame.
returns
  • ret 1 frame
observer:getlocationflags()since 1.5.1
Active location-class filter.
returns
  • ret 1 table
observer:getorientation()since 1.5.1
The observer's current orientation.
returns
  • ret 1 rotation
observer:getposition()since 1.5.1
The observer's current position in universal coordinates.
returns
  • ret 1 position
observer:getspeed()since 1.5.1
Get the observer's target speed.
returns
  • ret 1 number μly/s
observer:getsurface()since 1.5.1
Name of the alternate surface currently displayed.
returns
  • ret 1 string
observer:gettime()since 1.5.1
Simulation time the observer is rendering.
returns
  • ret 1 number Julian date (TDB)
observer:gettrackedobject()since 1.5.1
The tracked object (or nil).
returns
  • ret 1 object | nil
observer:goto(0…5 args)gotoobjectsince 1.5.1
`(target, [time])` or table form `{to=…, finalOrientation=…, duration=…, …}`. Travels to the target along an exponential ease-in/out curve.
  • arg 1 target object | position Destination (object centers it; position aims for it).
  • arg 2 travelTime number seconds default: 5 (seconds) Journey duration.
  • arg 3 startInter number 0.0–1.0 default: 0.25 Acceleration interpolation start fraction.
  • arg 4 endInter number 0.0–1.0 default: 0.75 Acceleration interpolation end fraction.
  • arg 5 accelTime number seconds default: 0.5 (seconds) Time to ramp up to cruising speed.
observer:gotodistance(1…5 args)since 1.5.1
`(target, distance, [time], [up], [upframe])` — travel until the observer is `distance` km from the target's center. `upframe` is one of the coordinate-system names (default `"universal"`).
  • arg 1 target object
  • arg 2 distance number km default: 20000 Final distance from object center. Default 20000 km.
  • arg 3 travelTime number seconds default: 5.0 Journey time.
  • arg 4 up vector Up vector.
  • arg 5 upframe string since 4ac5584 Frame the up vector is expressed in: "universal", "observer", "ecliptic", "equatorial", "bodyfixed", "lock", "chase". Default "universal".
observer:gotolocation(1…3 args)since 1.5.1
`(position, [duration], [rotation])` — travel to a `position` (interpreted in the current frame) over `duration` seconds, optionally rotating to the given final `rotation`.
  • arg 1 position position Target position. Interpreted in the observer's CURRENT frame.
  • arg 2 duration number seconds default: 5.0 Journey time.
  • arg 3 rotation rotation since 4ac5584 Optional final orientation.
observer:gotolonglat(1…6 args)since 1.5.1
`(target, longitude_rad, latitude_rad, [distance], [time], [up])` — travel to the body-fixed point at the given longitude/latitude.
  • arg 1 target object
  • arg 2 longitude number radians default: 0 East-positive longitude.
  • arg 3 latitude number radians default: 0 North-positive latitude.
  • arg 4 distance number km default: 5 × target radius Distance from object center; default = 5 × radius.
  • arg 5 travelTime number seconds default: 5.0 Journey duration.
  • arg 6 up vector Up vector for the camera (default Y-axis).
observer:gotosurface(1…2 args)since 1.5.1
`(target, [time])` — travel just above the body's surface at the current sub-observer point.
  • arg 1 target object
  • arg 2 travelTime number seconds default: 5.0
observer:isvalid()since 1.5.1
Whether the observer pointer is still valid (i.e. not destroyed via deleteview).
returns
  • ret 1 boolean
observer:lock(…)since 1.5.1
Set the secondary lock object for a phase-lock frame.
  • arg 1 target object
observer:lookat(2…3 args)since 1.5.1
`(to, up)` or `(from, to, up)` — orient the camera to look at a position with the given world-space up vector.
  • arg 1 from_or_to position When 3 args: from-position. When 2 args: to-position.
  • arg 2 to_or_up position | vector When 3 args: to-position. When 2 args: up-vector.
  • arg 3 up vector World-space up vector (3-arg form only).
observer:makeactiveview()since 1.6.1
Make this observer's view the active one.
observer:orbit(…)since 1.6.1
Apply a `rotation` orbiting around the simulation's current selection (one-shot).
  • arg 1 rotation rotation
observer:rotate(…)since 1.5.1
Apply a `rotation` to the observer's orientation (one-shot).
  • arg 1 rotation rotation
observer:setfov(1…2 args)since 1.5.1
Set the field of view. `syncZoom` defaults to true; pass `false` to write only `Observer::fov` and leave the per-view zoom unchanged (matches the legacy `set{name "FOV"}` cel command).
  • arg 1 fov number radians
  • arg 2 syncZoom boolean default: true since 4ac5584 If true (default), also writes the per-view zoom; pass false to leave per-view zoom unchanged.
observer:setframe(…)since 1.5.1
Set the observer's frame to a given `frame`.
  • arg 1 frame frame
observer:setlocationflags(…)since 1.5.1
Update the location-class filter from a {flagName=true|false, ...} table. Unknown keys are warned but ignored.
  • arg 1 flags table Table mapping location flag names to booleans.
observer:setorientation(…)since 1.5.1
Set the orientation from a `rotation`.
  • arg 1 orientation rotation
observer:setposition(…)since 1.5.1
Set the observer's position from a `position`.
  • arg 1 position position
observer:setspeed(…)since 1.5.1
Set the observer's target speed (μly/s) along its forward axis.
  • arg 1 speed number μly/s
observer:setsurface(…)since 1.5.1
Choose an alternate surface to display.
  • arg 1 name string
observer:singleview()since 1.5.1
Collapse all views into one (the current view).
observer:splitview(1…2 args)since 1.5.1
Split the active view: `(view, type, splitPos)` where `type` is `"v"` or `"h"`.
  • arg 1 type string "v" for vertical split, "h" for horizontal.
  • arg 2 splitPos number 0.0–1.0 default: 0.5 Number expected as argument to observer:splitview()
observer:synchronous(…)since 1.5.1
Set frame to body-fixed-centered on `target`.
  • arg 1 target object
observer:__tostring()since 1.5.1
String-conversion metamethod — invoked implicitly by `tostring(obj)` and `print`.
returns
  • ret 1 string
observer:track(…)since 1.5.1
Set tracked object (camera always faces it). Pass `nil` to clear.
  • arg 1 target object | nil
observer:travelling()since 1.5.1
Whether a goto/center journey is currently in progress.
returns
  • ret 1 boolean

object 40 methods

Selectable objects — bodies, stars, deep-sky objects, locations.

object:absmag()since 1.5.1
Return the absolute magnitude (stars/DSOs).
returns
  • ret 1 number magnitude
object:addreferencemark(…)since 1.6.1
Add a reference mark to this object. Takes a single options table. Recognized types: "body axes", "frame axes", "sun direction", "velocity vector", "spin vector", "body to body direction", "visible region", "planetographic grid", "terminator".
  • arg 1 options table Table with fields type (string, required), size (number, default = body radius), opacity (number, default uses each mark's built-in opacity), color (string, named color or "#rrggbb"), tag (string, defaults to type), and target (object, required for "body to body direction").
object:addtocategory()since e6e84d1
Add this object to a category by name.
  • arg 1 category category | string
object:bodyfixedframe()since 1.6.1
Return a body-fixed frame.
returns
  • ret 1 frame
object:bodyframe(0…1 args)since 1.6.1
Return the body frame (rotation reference) of the body.
  • arg 1 t number Julian date (TDB) default: current simulation time Time expected as argument to object:orbitframe
returns
  • ret 1 frame
object:catalognumber(…)since 1.6.1
Return the catalog number for a star in the named catalog, or nil if the star is not in that catalog or the object is not a star.
  • arg 1 catalogName string One of "HD", "SAO", or "HIP".
returns
  • ret 1 integer | nil
object:equatorialframe()since 1.6.1
Return an equatorial frame centered on the body.
returns
  • ret 1 frame
object:getcategories()since e6e84d1
Return a list of categories the object belongs to.
returns
  • ret 1 table
object:getchildren()since 1.5.1
Return an iterable of child bodies (planets of a star, moons of a planet…).
returns
  • ret 1 function Iterator over children.
object:getdensity()since 1d198c3
Return the body's mean density (g/cm³).
returns
  • ret 1 number g/cm³
object:getinfo()since 1.5.1
Return a Lua table of metadata (name, radius, oblateness, magnitude, etc.).
returns
  • ret 1 table
object:getmass()since 1d198c3
Return the body's mass in Earth masses. Only meaningful for bodies; returns nothing for stars, deep-sky objects, etc.
returns
  • ret 1 number Earth masses
object:getphase(0…1 args)since 1.6.1
Return the active timeline phase at the current time.
  • arg 1 t number Julian date (TDB) default: current simulation time Time expected as argument to object:getphase
returns
  • ret 1 phase
object:getposition(0…1 args)since 1.5.1
`([t])` — return the universal `position` of the object at simulation time `t` (default: current).
  • arg 1 t number Julian date (TDB) default: current simulation time Defaults to current simulation time.
returns
  • ret 1 position
object:gettemperature()since 1d198c3
Return the temperature in kelvin. For bodies, the surface temperature at the current simulation time; for stars, the effective surface temperature. Returns nothing when no temperature is available.
returns
  • ret 1 number K
object:localname()since 1.5.1
Return the object's localized name.
returns
  • ret 1 string
object:locations()since 1.6.1
Return an iterable of named surface locations.
returns
  • ret 1 function Iterator over locations.
object:mark(0…6 args)since 1.5.1
`(color_string, [symbol], [size], [alpha], [label], [occludable])` — place a marker on the object.
  • arg 1 color string 0.0–1.0 (color component) or hex string Hex color or named color.
  • arg 2 symbol string "diamond", "triangle", "square", "plus", "x", "leftarrow", "rightarrow", "uparrow", "downarrow", "circle", "disk".
  • arg 3 markSize number pixels default: 10.0
  • arg 4 alpha number 0.0–1.0 default: 0.9
  • arg 5 label string
  • arg 6 occludable boolean default: true since 1.6.1
object:name()since 1.5.1
Return the object's primary name.
returns
  • ret 1 string
object:orbitcoloroverridden()since 1.6.1
Whether the body's orbit color is overridden.
returns
  • ret 1 boolean
object:orbitframe(0…1 args)since 1.6.1
Return the orbit frame of the body.
  • arg 1 t number Julian date (TDB) default: current simulation time Time expected as argument to object:orbitframe
returns
  • ret 1 frame
object:orbitvisibility()since 1.6.1
Get the orbit-display mode: `"never"`, `"normal"`, or `"always"`.
returns
  • ret 1 string
object:phases()since 1.6.1
Return an iterable over all timeline phases.
returns
  • ret 1 function Iterator over phases.
object:preloadtexture()since 1.5.1
Preload the body's surface textures.
object:radius()since 1.5.1
Return the body's mean radius in km.
returns
  • ret 1 number km
object:removefromcategory()since e6e84d1
Remove this object from a category.
  • arg 1 category category | string
object:removereferencemark(0…999 args)since 1.6.1
Remove a reference mark by name.
object:setatmosphere(…)since 1.5.1
Override atmosphere parameters for the body. Takes a single options table; unknown keys are warned but ignored.
  • arg 1 options table Supported keys: height (number), mie (number), miescaleheight (number), mieasymmetry (number), rayleigh (3-number table), absorption (3-number table), lowercolor (3-number table), uppercolor (3-number table), skycolor (3-number table), sunsetcolor (3-number table).
object:setcloudtexture(1…2 args)since d9dee7e
Override the cloud texture: `(texture_name, [path])`.
object:setorbitcolor(…, …, …)since 1.6.1
Set an explicit orbit color. All three components are required. Only effective for body objects.
  • arg 1 r number 0.0–1.0
  • arg 2 g number 0.0–1.0
  • arg 3 b number 0.0–1.0
object:setorbitcoloroverridden(…)since 1.6.1
Toggle the orbit-color override.
  • arg 1 overridden boolean
object:setorbitvisibility(…)since 1.6.1
Set the orbit-display mode.
  • arg 1 mode string "never", "normal", or "always".
object:setradius(…)since 1.5.1
Override the body's radius (km).
  • arg 1 radius number km
object:setringstexture(1…2 args)since e92af93
Override the rings texture for a ringed body.
object:setvisible(…)since 1.6.1
Set the visibility flag. Works on bodies and deep-sky objects; no-op for other selection types.
  • arg 1 visible boolean
object:spectraltype()since 1.5.1
Return the spectral type string (stars).
returns
  • ret 1 string
object:__tostring()since 1.5.1
String-conversion metamethod — invoked implicitly by `tostring(obj)` and `print`.
returns
  • ret 1 string
object:type()since 1.5.1
Return the object kind: `"star"`, `"body"`, `"deepsky"`, `"location"`, or `"null"`.
returns
  • ret 1 string "star", "body", "deepsky", "location", or "null".
object:unmark()since 1.5.1
Remove markers from this object.
object:visible()since 1.6.1
Whether the body is currently flagged visible.
returns
  • ret 1 boolean

position 12 methods

High-precision universal coordinates.

position:__add(…)since 1.5.1
Position + position → new position (component-wise).
  • arg 1 p2 position | vector
returns
  • ret 1 position
position:addvector(…)since 1.5.1
Return a new position offset by a vector (micro-light-years).
  • arg 1 v vector μly
returns
  • ret 1 position
position:distanceto(…)since 1.5.1
Distance to another position, in km.
  • arg 1 target position
returns
  • ret 1 number km
position:getx()since 1.5.1
X component (R128 high-precision, returned as Lua number).
returns
  • ret 1 number
position:gety()since 1.5.1
Y component.
returns
  • ret 1 number
position:getz()since 1.5.1
Z component.
returns
  • ret 1 number
position:__index(…)since 1.5.1
Field-access metamethod (allows `p.x`, `p.y`, `p.z`).
  • arg 1 key string Invalid key in position-access
returns
  • ret 1 number
position:__newindex(…, …)since 1.5.1
Field-assignment metamethod.
  • arg 1 key string Invalid key in position-access
  • arg 2 value number
position:orientationto(…, …)since 1.5.1
`(target, up)` — return the rotation that points from this position to `target` with the given up vector.
  • arg 1 target position
  • arg 2 up vector
returns
  • ret 1 rotation
position:__sub(…)since 1.5.1
Position − position returns the offset vector between them. Position − vector returns a new position offset by the inverse of the vector.
  • arg 1 other position | vector
returns
  • ret 1 vector | position Vector when subtracting a position, position when subtracting a vector.
position:__tostring()since 1.5.1
String representation.
returns
  • ret 1 string
position:vectorto(…)since 1.5.1
Vector from this position to another, in micro-light-years.
  • arg 1 target position
returns
  • ret 1 vector μly

rotation 10 methods

Quaternion-backed orientations.

rotation:__add(…)since 1.5.1
Component-wise addition (rarely useful directly).
  • arg 1 q2 rotation
rotation:imag()since 1.5.1
Imaginary (x, y, z) components as a `vector`.
returns
  • ret 1 vector
rotation:__index(…)since 1.5.1
Field-access metamethod.
  • arg 1 key string Invalid key in rotation-access
returns
  • ret 1 number
rotation:__mul(…)since 1.5.1
Quaternion product (compose rotations).
  • arg 1 r2 number | rotation
returns
  • ret 1 rotation
rotation:__newindex(…, …)since 1.5.1
Field-assignment metamethod.
  • arg 1 key string Invalid key in rotation-access
  • arg 2 value number
rotation:real()since 1.5.1
Scalar (w) component.
returns
  • ret 1 number
rotation:setaxisangle(…, …)since 1.5.1
Set the rotation from `(axis_vec, angle_radians)`.
  • arg 1 axis vector
  • arg 2 angle number radians
rotation:slerp(…, …)since 1.5.1
`(target, t)` — spherical linear interpolation toward another rotation, parameterized by `t` ∈ [0, 1].
  • arg 1 target rotation
  • arg 2 t number 0.0–1.0 Interpolation parameter.
returns
  • ret 1 rotation
rotation:__tostring()since 1.5.1
String representation.
returns
  • ret 1 string
rotation:transform(…)since 1.5.1
Apply this rotation to a vector and return the rotated vector.
  • arg 1 v vector
returns
  • ret 1 vector

vector 12 methods

Three-component vectors.

vector:__add(…)since 1.5.1
Vector + vector returns the component-wise sum (a new vector). Vector + position returns a new position offset by the vector.
  • arg 1 other vector | position
returns
  • ret 1 vector | position Vector when adding two vectors, position when adding a position.
vector:getx()since 1.5.1
X component.
returns
  • ret 1 number
vector:gety()since 1.5.1
Y component.
returns
  • ret 1 number
vector:getz()since 1.5.1
Z component.
returns
  • ret 1 number
vector:__index(…)since 1.5.1
Field-access metamethod.
  • arg 1 key string Invalid key in vector-access
returns
  • ret 1 number
vector:length()since 1.5.1
Euclidean length.
returns
  • ret 1 number
vector:__mul(…)since 1.5.1
Vector × scalar returns a scaled vector. Vector ⋅ vector returns the dot product. Vector × rotation rotates the vector through the quaternion product and returns the resulting rotation.
  • arg 1 other number | vector | rotation
returns
  • ret 1 vector | number | rotation Vector for scalar multiplication, number for dot product, rotation when multiplied by a rotation.
vector:__newindex(…, …)since 1.5.1
Field-assignment metamethod.
  • arg 1 key string Invalid key in vector-access
  • arg 2 value number
vector:normalize()since 1.5.1
Return a unit vector along the same direction.
returns
  • ret 1 vector
vector:__pow(…)since 1.5.1
Cross product `a ^ b`.
  • arg 1 v2 vector
returns
  • ret 1 vector Cross product.
vector:__sub(…)since 1.5.1
Vector − vector.
  • arg 1 op2 vector
returns
  • ret 1 vector
vector:__tostring()since 1.5.1
String representation.
returns
  • ret 1 string

frame 6 methods

Reference frames (universal, ecliptical, equatorial, body-fixed, etc.).

frame:from(1…2 args)since 1.5.1
Convert a position or rotation from this frame into universal coordinates.
  • arg 1 value position | rotation
  • arg 2 t number Julian date (TDB) default: current simulation time
returns
  • ret 1 position | rotation Same kind as the input.
frame:getcoordinatesystem()since 1.5.1
Return the coordinate system name (`"universal"`, `"ecliptic"`, `"equatorial"`, `"bodyfixed"`, `"observer"`, `"lock"`, `"chase"`).
returns
  • ret 1 string
frame:getrefobject()since 1.5.1
Return the frame's reference object (or nil for `"universal"`).
returns
  • ret 1 object | nil
frame:gettargetobject()since 1.5.1
Return the frame's target object (or nil). Most relevant for "lock" frames, where it identifies the secondary body.
returns
  • ret 1 object | nil
frame:to(1…2 args)since 1.5.1
Convert a position or rotation from universal coordinates into this frame.
  • arg 1 value position | rotation
  • arg 2 t number Julian date (TDB) default: current simulation time
returns
  • ret 1 position | rotation Same kind as the input.
frame:__tostring()since 1.5.1
String representation.

phase 6 methods

Timeline phases — orbit and rotation segments scoped to a time interval.

phase:bodyframe()since 1.6.1
Frame in which the phase's rotation is defined.
returns
  • ret 1 frame
phase:getorientation(…)since 1.6.1
Orientation in this phase's body frame at time tdb. Times outside the phase's span are clamped to its start or end.
  • arg 1 tdb number Julian date (TDB)
returns
  • ret 1 rotation
phase:getposition(…)since 1.6.1
Position in this phase's orbit frame at time tdb. Times outside the phase's span are clamped to its start or end.
  • arg 1 tdb number Julian date (TDB)
returns
  • ret 1 position
phase:orbitframe()since 1.6.1
Frame in which the phase's orbit is defined.
returns
  • ret 1 frame
phase:timespan()since 1.6.1
Return the `(start, end)` Julian dates of the phase.
returns
  • ret 1 number Julian date start
  • ret 2 number Julian date end
phase:__tostring()since 1.6.1
String representation.
returns
  • ret 1 string

category 9 methods

Object categorization.

category:addobject()since e6e84d1
Add an object to the category.
  • arg 1 obj object
returns
  • ret 1 boolean
category:createchild()since e6e84d1
Create a child category.
  • arg 1 name string Category name.
  • arg 2 domain string default: "" Optional translation domain.
returns
  • ret 1 category | nil
category:deletechild()since e6e84d1
Delete a child category.
  • arg 1 name_or_category string | category
returns
  • ret 1 boolean
category:getchildren()since e6e84d1
Return a list of child categories.
returns
  • ret 1 table
category:getname()since e6e84d1
Return the category's name.
  • arg 1 i18n boolean
returns
  • ret 1 string
category:getobjects()since e6e84d1
Return a list of objects in the category.
returns
  • ret 1 table
category:haschild()since e5e229d
Whether a child category with the given name exists.
  • arg 1 name_or_category string | category
returns
  • ret 1 boolean
category:removeobject()since e6e84d1
Remove an object from the category.
  • arg 1 obj object
returns
  • ret 1 boolean
category:__tostring()since e6e84d1
String representation.

font 9 methods

Loaded font handles. Used for measuring and drawing text.

font:bind()since 1.5.1
Bind the font for direct OpenGL drawing.
font:getheight()since 1.5.1
Line height of the font in pixels.
returns
  • ret 1 number pixels
font:getmaxascent()since e60ddf6
Maximum glyph ascent in pixels.
returns
  • ret 1 number pixels
font:getmaxdescent()since e60ddf6
Maximum glyph descent in pixels.
returns
  • ret 1 number pixels
font:gettextwidth(…)since e60ddf6
Pixel width of a string in this font.
  • arg 1 text string
returns
  • ret 1 number pixels
font:getwidth(…)since 1.5.1
Pixel width of the given string in this font. Equivalent to gettextwidth.
  • arg 1 s string
returns
  • ret 1 number pixels
font:render(…)since 1.5.1
Render text using the current GL projection and modelview matrices. Returns the X coordinate of the layout's pen position after the run.
  • arg 1 text string
returns
  • ret 1 number pixels X coordinate of the pen after rendering.
font:__tostring()since 1.5.1
String representation.
font:unbind()since d924320
Unbind the font from OpenGL.

image 3 methods

Decoded image handles.

image:getheight()since 1.5.1
Image height in pixels.
returns
  • ret 1 number pixels
image:getwidth()since 1.5.1
Image width in pixels.
returns
  • ret 1 number pixels
image:__tostring()since 1.5.1
String representation.

texture 4 methods

GL texture handles.

texture:bind()since 1.5.1
Bind the texture for OpenGL drawing.
texture:getheight()since 1.5.1
Texture height in pixels.
returns
  • ret 1 number pixels
texture:getwidth()since 1.5.1
Texture width in pixels.
returns
  • ret 1 number pixels
texture:__tostring()since 1.5.1
String representation.

celscript 2 methods

Embedded cel-script objects, runnable from a celx script.

celscript:tick()since 1.5.1
Advance the embedded cel script by `dt` seconds.
celscript:__tostring()since 1.5.1
String representation.
returns
  • ret 1 string

gl / glu 19 methods

Low-level OpenGL drawing primitives (subset; for overlay rendering). Most calls live on the global gl table; LookAt and Ortho2D are exposed on the glu table instead.

gl.Begin(...)since 1.5.1
glBegin equivalent: `(GL_LINES | GL_TRIANGLES | GL_QUADS | …)`.
  • arg 1 mode GL enum default: 0 GL_LINES, GL_TRIANGLES, GL_QUADS, etc.
gl.BlendFunc(...)since 1.5.1
Configure the blend function for the color channels. Internally calls glBlendFuncSeparate(sfactor, dfactor, GL_ZERO, GL_ONE), so the alpha channel always uses GL_ZERO/GL_ONE regardless of the values passed here.
  • arg 1 sfactor GL enum Source RGB blend factor (e.g. GL_SRC_ALPHA).
  • arg 2 dfactor GL enum Destination RGB blend factor (e.g. GL_ONE_MINUS_SRC_ALPHA).
gl.Color(...)since 1.5.1
Set draw color (RGBA).
  • arg 1 r number 0.0–1.0 (color component) default: 0
  • arg 2 g number 0.0–1.0 (color component) default: 0
  • arg 3 b number 0.0–1.0 (color component) default: 0
  • arg 4 a number 0.0–1.0 (color component) default: 0
gl.Disable(...)since 1.5.1
Disable a GL state.
  • arg 1 cap GL enum default: 0
gl.Enable(...)since 1.5.1
Enable a GL state.
  • arg 1 cap GL enum default: 0
gl.End(...)since 1.5.1
glEnd equivalent.
gl.Frustum(...)since 1.5.1
Set up a frustum projection (glFrustum).
  • arg 1 left number
  • arg 2 right number
  • arg 3 bottom number
  • arg 4 top number
  • arg 5 n number Near plane.
  • arg 6 f number Far plane.
gl.LineWidth(...)since 1.5.1
Set line drawing width.
  • arg 1 width number pixels default: 1
gl.LoadIdentity(...)since 1.5.1
Replace current matrix with identity.
glu.LookAt(...)since 1.5.1
Set up a look-at view matrix.
  • arg 1 ix number default: 0
  • arg 2 iy number default: 0
  • arg 3 iz number default: 0 Eye position.
  • arg 4 cx number default: 0
  • arg 5 cy number default: 0
  • arg 6 cz number default: 0 Center (look-at) point.
  • arg 7 ux number default: 0
  • arg 8 uy number default: 0
  • arg 9 uz number default: 0 Up vector.
gl.MatrixMode(...)since 1.5.1
Switch active matrix stack.
  • arg 1 mode GL enum default: 0
gl.Ortho(...)since 1.5.1
Set up an orthographic projection (glOrtho).
  • arg 1 left number
  • arg 2 right number
  • arg 3 bottom number
  • arg 4 top number
  • arg 5 n number Near plane.
  • arg 6 f number Far plane.
glu.Ortho2D(...)since 1.5.1
Set up a 2D orthographic projection (gluOrtho2D).
  • arg 1 left number
  • arg 2 right number
  • arg 3 bottom number
  • arg 4 top number
gl.PopMatrix(...)since 1.5.1
Restore previous matrix.
gl.PushMatrix(...)since 1.5.1
Save current matrix.
gl.TexCoord(...)since 1.5.1
Set texture coordinate.
  • arg 1 x number default: 0
  • arg 2 y number default: 0
gl.TexParameter(...)since 1.5.1
Configure texture sampling (glTexParameteri). All three arguments are required.
  • arg 1 target GL enum Texture target (e.g. GL_TEXTURE_2D).
  • arg 2 pname GL enum Parameter name (e.g. GL_TEXTURE_MIN_FILTER).
  • arg 3 value GL enum Parameter value (e.g. GL_LINEAR).
gl.Translate(...)since 1.5.1
Translate the model-view matrix.
  • arg 1 x number default: 0
  • arg 2 y number default: 0
gl.Vertex(...)since 1.5.1
Set vertex position.
  • arg 1 x number default: 0
  • arg 2 y number default: 0