Lua Scripting in TI-Nspire™

Getting Started with Lua Scripting in TI-Nspire™

TI has developed a series of tutorials that begin with introducing you to Lua scripting and advance to showing you how to create TI-Nspire™ documents. Get started here.

Try this simple “Hello World” script using the Lua Script Editor that is built-in to the TI-Nspire™ software.

• Step 1: Insert a new page to your document (Insert > Script Editor > Insert Script).
  
  
  
  

• Step 2: Name your new script and click OK
  
  
  
  

• Step 3: Enter this code in the Script Editor window
  
  function on.paint(gc)
  gc:drawString(“hello world”, 0, 20)
  end
  
  
  
  

• Step 4: Click Set Script, which tells the editor to run your script
  
  

For more tutorials please visit Compass Learning Technologies' Lua website.

TI-Nspire™ Lua Script Editor

Reference Guide

Scripts can access most components of the TI-Nspire™ family through Lua extensions to provide new avenues for students to explore interactive math and science content.

For more information about using Lua Scripting, view the Lua Scripting API Reference Guide. This reference guide has been updated to include scripting documentation for the TI-Nspire™ App for iPad®.

The guide shows how content developers can create scripts that enable students to:

• Interact with compelling graphical interfaces
• Perform advanced mathematical calculations
• Respond in real time to Vernier data collection probes
• Share data with other script documents and built-in TI-Nspire™ applications

Each script resides in a page or in one pane of a page of a .tns document and can be used across built-in applications and scripts in multiple pages to create:

• Lesson material with instructions
• Presentations
• Simulations
• Interactive exploration
• Educational games 

Resources

Users with any level of understanding of the Lua programming language will find this style guide’s list of dos and don'ts extremely helpful.

Overall Guidelines

• Use short phrases
  Short phrases translate across platforms better and users are more likely to read them in the entirety rather than skim or skip.
• Use images rather than words
  Images can more quickly and powerfully convey meaning than words. Ensure that images look good and are sized appropriately for all platforms.
• Don’t interrupt the flow
  Use notifications rather than dialogs when possible. Keep the user in control of the experience.
• Show only what is needed when it is needed
  Don’t overwhelm the user with choices. Also, this will translate better to constrained platforms.
• Stay consistent
  Make sure controls which operate the same look the same and are placed the same.
• Provide continuous feedback
  Help the user know when they are progressing through continuous feedback on their actions.

Variables Usage Guidelines

• Global usage
  If a variable can be declared as a local, do so. Global variables can be accessed throughout the script, making accidental use and naming collisions more likely and making the script harder to maintain and debug. As a side benefit, local variable access is much quicker than global variable access so your scripts will operate faster using them rather than global variables.
• Variable Usage
  Lua is a garbage collected environment. That is, when Lua determines that a variable is no longer being used, it is free to reclaim the memory used by the variable. This means that as a programmer, you don’t need to worry about managing the creation and release of memory. However, garbage collection can be an expensive operation and cause a poor experience to the user. To reduce the amount of garbage collection, avoid creating lots of unnecessary objects. This can be done by determining if a variable is really necessary and removing it if not, reusing objects instead of repeatedly creating new ones, and using local variables. For further information about ways to minimize the garbage collection in Lua, see the following article.
• Table Usage
  Table creation is a deceptively simple operation in the Lua programming language. Unfortunately, it is also an expensive operation with a lot going on behind the scenes. It is best to avoid creating large numbers of tables. This is especially true in routines which are meant to operate quickly such as event and particularly paint handlers. Where possible, instead of creating many tables, reorganize the data to avoid table creation or reuse the Lua tables. As an example of data reorganization, using the following data structure. Additionally, table iterations can be a source of performance issues if not done thoughtfully. Where possible, iterate using numerical indices using the ‘ipairs’ function rather than keys using the ‘pairs’ function.
• Variable Naming
  There are many different styles used by programmers in terms of variable naming. The important thing here is to be consistent in how variables are named. For instance, if variable whose value should not be modified are all caps in part of the script, then all variables that are meant to be constant should be all caps.

Image Resource Guidelines

• Images
  Judicious use of images adds a lot of value to TI-Nspire™ Lua scripts. However, care must be taken when using images on the TI-Nspire™ platform due to the high resource constraints they can place on the system.
• Size
  Images used should be no larger than absolutely necessary so be sure that they are cropped of any unnecessary pixels. Smaller images use significantly less memory and perform much better when modified and when they are displayed on the screen. As a guideline, keep each individual image smaller than 640x480 and keep the total of all images used by all scripts within a single document to ideally less than 500,000 pixels and at a maximum 1,000,000 pixels for a color device.
• Reuse
  Images should be reused wherever possible. For example, if a script uses several button images that are actually the same visual image, then they should also use the same image data instead of importing the data multiple times. Since the images used in TI-Nspire™ are all bitmapped images, they may not smoothly scale when resizing them. Consider using separate base images for handheld and non-handheld images. This will deliver a better visual on each platform while also removing the need to scale images on the handheld. Balance the desire to deliver images which take advantage of the platform, though, with the size constraints for images described in the Resource Guidelines.

Cross-Platform Design Guidelines

• To provide a great user experience, the Lua scripts need to look great, deliver an experience consistent with the rest of the TI-Nspire™ platform, be intuitive to operate, and work well across all the various platforms upon which TI-Nspire™ is delivered. 
• To achieve the consistent experience, it is important to ensure that all objects maintain their same relative positions and sizes across the different platforms. Additionally, the sizes need to be updated as the screen sizes change, such as by resizing the TI-Nspire™application on the desktop.

• Lua
• Inspired-Lua Wiki
• Lua HQ: Compass Learning Technologies
• Lua Style Guide
• Optimizing Local Variables