Roku App development: Beginner’s Guide

Welcome to the world of Roku development! In this guide, we’ll walk you through the essential steps to set up your Roku project, from crafting a comprehensive manifest file to structuring your source and components directories. Let’s get started on your journey to mastering SceneGraph app development for Roku.

Create an application directory with the following minimum subdirectories and files:

• manifest file
• source directory
• components directory
• images directory

YourRokuApp/
│
├── manifest
│   └── YourManifestFile
│
├── source
│   └── main.brs
│
├── components
│   └── rectangleScene.xml
│
└── images
    ├── Icon_HD.png
    ├── Icon_SD.png
    ├── splash_sd.jpg
    └── splash_hd.jpg

In the above structure:

The YourRokuApp directory is the main directory for your Roku application.

The manifest directory contains your manifest file (YourManifestFile), defining essential details about your application.

The source directory holds your main BrightScript file (main.brs) responsible for initiating the application and creating the SceneGraph scene.

The components directory includes XML and BrightScript files defining your SceneGraph components. In this example, rectangleScene.xmlcorrespond to the SceneGraph scene named "rectangleScene."

The images directory contains graphic files used in your application, as referenced in the manifest file.

Manifest File Essentials:

Your manifest file serves as the blueprint for your Roku application. Here’s a breakdown of key fields to ensure a seamless development experience:

// your mainfest file

title=Your_Roku_App_Name
subtitle=Your_App_Subtitle
major_version=1
minor_version=0
build_version=00001

mm_icon_focus_hd=pkg:/images/Icon_HD.png
mm_icon_focus_sd=pkg:/images/Icon_SD.png

splash_screen_sd=pkg:/images/splash_sd.jpg
splash_screen_hd=pkg:/images/splash_hd.jpg
splash_color=#000000
splash_min_time=1000

Customize the above fields according to your application details, providing a solid foundation for your SceneGraph project.

Setting Up the Source Directory:

Your source directory houses the BrightScript code driving your application’s main execution thread. The main.brs file initialize your app and creates the SceneGraph scene. Here's a example:

'main.brs

sub Main()
    showChannelSGScreen()
end sub

sub showChannelSGScreen()
    ' The roSGScreen object is a SceneGraph canvas that displays the contents of a Scene node instance
    screen = CreateObject("roSGScreen")
    ' message port is the place where events are sent
    m.port = CreateObject("roMessagePort")
    ' sets the message port which will be used for events from the screen
    screen.SetMessagePort(m.port)
    ' every screen object must have a Scene node, or a node that derives from the Scene node
    scene = screen.CreateScene("rectangleScene")
    screen.Show() ' Init method in MainScene.brs is invoked

    while(true)
        msg = wait(0, m.port)
        msgType = type(msg)

        if msgType = "roSGScreenEvent"
            if msg.isScreenClosed() then return
        end if
    end while
end sub

You can use this example main.brs file for your SceneGraph applications simply by adding the name of a Screen Graph scene defined in an XML component file, such as posterScene, as follows:

scene = screen.CreateScene("my_scene")

For example:

scene = screen.CreateScene("posterScene")

Similarly, you can control the flow of scenes through your application by creating and showing scenes as needed:

screen = CreateObject("roSGScreen")
m.port = CreateObject("roMessagePort")
screen.setMessagePort(m.port)
scene = screen.CreateScene("another_scene")
screen.show()

Components Directory Structure:

The components directory is where your SceneGraph scenes come to life. Each XML component file pairs with its corresponding BrightScript code. Here’s a snippet illustrating a basic SceneGraph XML component:

//rectangleScene.xml
<?xml version="1.0" encoding="utf-8" ?>

<component name="rectangleScene" extends="Scene">

    <script type="text/brightscript">
        <![CDATA[
            sub init()
                m.top.setFocus(true)
            end sub
        ]]>
    </script>

    <children>
        <Rectangle
            id="bottomRectangle"
            color="0x0000FFFF"
            width="1280"
            height="60"
            translation="[0,620]" 
        />
    </children>

</component>

In the above example, the SceneGraph component is a definition of a Scene node class named rectangleScene. The component definition consists of a <script> element, which defines some BrightScript code to be used to initialize rectangleScene, and a Rectangle node definition, that defines the location, size, and color of a rectangle to be shown on the display screen, with a node ID of bottomRectangle.

Feel free to modify this example to create the SceneGraph components your application demands.

Images Directory for Visual Appeal:

Follow the convention of using the pkg:/ resource prefix for URI paths.

Any graphic image files to be included in the application package itself should be copied into the images directory. As a minimum, the images directory must contain the application selection and splash screen graphic files. Other graphic files used in the application that will not be downloaded from your server should also be copied into the images directory.

Run Brightscript on your local machine with brs module.

BRS: Off-Roku BrightScript npm package

An interpreter for the BrightScript language that runs on non-Roku platforms.

Install brs using > npm i brs

Executing a BRS file:

$ cat hello-world.brs
?"Dennis Ritchie said ""Hello, World!"""

$ brs hello-world.brs
Dennis Ritchie said "Hello, World!"

As you embark on your Roku SceneGraph app development journey, refer to Roku’s official documentation for in-depth insights into SceneGraph core concepts, API references, and practical samples. Happy coding!

Your manifest file serves as the blueprint for your Roku application. Here’s a breakdown of key fields to ensure a seamless development experience: