Setup Lightning SDK

We will use the Lightning SDK to power the app which can be found here: https://github.com/rdkcentral/Lightning-SDK/

This tutorial has been written for Lightning SDK after 22 January 2020, which uses a new approach of the SDK. Make sure you are running the latest version

This getting started with Lightning document will guide you through the first steps of building an app with Lightning.

This guide consist of 3 main topics:

  1. Setting up your environment
  2. Develop your app
  3. Run, test and deploy

We have chosen to guide you in creating a fully functioning game called Tic Tac Toe, for those unfamiliar with the game I suggest checking out: https://en.wikipedia.org/wiki/Tic-tac-toe

Setting up your environment

  1. Start by installing the Lightning-CLI (Command-line interface) npm install -g rdkcentral/Lightning-CLI
  2. Navigate to a folder on your machine where you want to place your project
  3. On the command-line type: lng to see all the available options.
  4. type lng create to create a new Lightning app
  5. Type the name TicTacToe
  6. Next fill in the identifier com.company.app.TicTacToe (or something that is more suitable to your situation)
  7. Choose if you want to enable ESlint or not.
  8. Next select yes for installing the NPM dependencies
  9. Choose yes for initializing an empty GIT repository

After the dependencies are successfully installed you can navigate to the created app folder (in our example cd com.metrological.app.TicTacToe).

We now have a couple of options:

  1. lng build will create a standalone bundle that you can run in the browser
  2. lng serve will start a local webserver and run the app
  3. lng dev will build the app, start a webserver and watch for changes

You can use these whenever you want throughout this getting started .

App contents

When you inspect the contents in your app folder you will find the following files:

  • README.md a markdown readme file that can hold instructions for configuration, installation, changelogs etc.
  • metadata.json this hold the following app related metadata:
{
  "name": "TicTacToe",
  "identifier": "com.metrological.app.TicTacToe",
  "version": "1.0.0",
  "icon": "./static/icon.png"
}
  • package.json this file holds various metadata relevant to the project
{
  "name": "com.metrological.app.TicTacToe",
  "description": "TicTacToe",
  "dependencies": {
    "@lightningjs/sdk": "^3.0.0"
  }
}
  • package-lock.json is automatically generated for any operations where npm modifies either the node_modules tree, or package.json. Read more...
  • settings.json which holds app and platform specific settings.
{
  "appSettings": {
    "stage": {
      "clearColor": "0x00000000",
      "useImageWorker": true
    },
    "debug": false
  },
  "platformSettings": {
    "inspector": false,
    "path": "./static",
    "log": false,
    "showVersion": true,
    "imageServerUrl": "//cdn.metrological.com/image",
    "proxyUrl": "//cdn.metrological.com/proxy",
    "textureMode": true
  }
}
  1. clearColor, specifies the color we use when we call the clear() method
  2. ImageWorker, if the platform you run the code on support Web workers
  3. Debug, toggles debug mode on / off
  4. Inspector, when set to true it will render out a HTML structure inside the DOM so you can inspect why certain elements are maybe rendered off-screen
  5. path, the path to the static app assets, Utils.asset() will use this folder to lookup assets
  6. log, toggles app logging on / off
  7. showVersion, if set to true, will overlay the app's version in the corner (version specified in metadata.json)
  8. imageServerUrl, if you have an image resizing server set the value to the endpoint
  9. proxyUrl, if you have access to a proxy server (i.e to cache data to speed up network request) you set the value to the endpoint
  10. textureMode, specifiy if you want to render video as a texture on the active drawing canvas

Please refer to the stage settings docs page for more information for more options.

Inside the src folder we can find a file called index.js, this file is responsible for launching your app:

import { Launch } from '@lightningjs/sdk'
import App from './App.js'

export default function () {
    return Launch(App, ...arguments)
}

This is the first time we really touch the SDK. The SDK has been developed with a modular approach in mind, therefore you can control which of its modules of the SDK you want to use.

Eventually when we bundle and run the game, our bundler (rollup) will add the imported modules to the bundle so we keep an optimized codebase (no un-used code). This method is often referred to as treeshaking.

  1. We import Launch method from the SDK (will act as a bootstrapper)
  2. Next we import our app from the App.js
  3. Export a function which upon invocation will Launch the app

Now that we have a basic setup we can move over to the next phase, the actual development of the App.

← Setup LightningStart Development →