Scripting Quickstart Guide

From Reflex Wiki
Jump to: navigation, search
by newborn
This article is a stub. You can help by expanding it!
A quick introduction on user interface scripting for Reflex using the LUA script language to create widgets that display real-time information on the player's HUD.

Hopefully, I will get a chance to write up a more detailed overview of the UI scripting but right now we are in "new update frenzy" mode, collecting bugs and squashing them etc.

Where to find the basic resources?

  • LuaFunctions.txt in the game folder contains a list of the built-in LUA functions for things like getting/setting console values, doing input, drawing pretty boxes etc.
  • LuaVariables.txt in the game folder contains a list of variables that are currently passed to the UI system such as maps, game modes, player information, etc.
  • LUA scripts are stored in base\internal\ui\
    • HUD scripts are in the "widgets" folder.
    • Menu scripts are in the "menus" folder.
    • SVGs are stored in the "icons" folder.

On script naming and pathing

  • If you are creating new scripts, try not to stomp on any official stuff (unless it is something you are hoping for us to include in an official update). You should give your custom widgets names that are unlikely to conflict with other peoples work, like "newborn_fancyHealth".
  • You can actually put these scripts in any path so if you are making a full HUD, you might want to create a folder such as base\internal\ui\<yourname> and put everything in there.

Coding and live updates

  • Scripts are all updated live so there is no need to restart Reflex to see the changes. Just save your .lua and you will see the changes immediately in-game. There is one catch to this - if you create a new file, you will need to restart Reflex before the game is able to see it.

Important console commands

  • There are some key console commands you will want to know. These are also stored in game.cfg:
    • ui_hide_widget <widgetname> will hide a widget.
    • ui_set_widget_scale <widgetname> <number> will scale a widget.
    • ui_set_widget_anchor <widgetname> <x> <y> will set the widgets anchor. For <x>, -1 is left, 0 is middle, 1 is right. For <y>, -1 is top, 0 is middle, 1 is bottom.
    • ui_set_widget_offset <widgetname> <x> <y> will set the widgets offset relative to the anchor.
  • All X and Y coordinates in scripts are relative to their anchors.

Avoid hard-coding coordinates

  • Where possible, design your widgets to use the offset and anchor console commands, instead of hard-coding positions into the lua script. For example, if you want a widget to be 100 from the bottom, do not just anchor it to the bottom and use -100 as the position in the script (use 0 as the position in the script and set the offset cvar to -100). This makes it a lot easier for users to reposition things themselves without delving into intimidating and frequently stomped scripts.
  • The ui_show_axis 1 console command will show the anchor points and offsets for all widgets on the screen. The centre of the red cross will be position 0,0 in your lua scripts.

Font usage

  • Fonts are loaded from base/internal/fonts/ and can be referred to by filename - for example, nvgFontFace("comic-sans").
  • Before distributing fonts with your HUD, keep in mind that most font licenses prohibit redistributing the .TTF source. If you search for fonts licensed under the SIL Open Font License (OFL), this license allows redistribution.

Widgets and potential "lag"

  • The WidgetName:draw function is called every frame. Ideally, do as little work in this as possible - the sooner you can early-out the better. You definitely can kill FPS with complex scripts called every frame.