SceneGraph na prática: XML + BrightScript no desenvolvimento de apps Roku

O Scene­Graph é o coração do desen­volvi­men­to mod­er­no de aplica­tivos para Roku. Mais do que uma sim­ples cama­da visu­al, ele define como a UI é estru­tu­ra­da, como os even­tos fluem e como o BrightScript se conec­ta ao com­por­ta­men­to real do app. Quem dom­i­na Scene­Graph deixa de “brigar com a platafor­ma” e pas­sa a con­stru­ir apps estáveis, per­for­máti­cos e aprova­dos com mais facil­i­dade.

Este arti­go é um guia humano, profis­sion­al e apro­fun­da­do, foca­do em uso real, não em teo­ria sol­ta. Aqui você vai enten­der como XML e BrightScript tra­bal­ham jun­tos, quais são os padrões cor­re­tos e por que Scene­Graph é deci­si­vo para apps VOD, FAST e pro­je­tos de stream­ing em escala.

---

O que é SceneGraph (além da definição oficial)

Tec­ni­ca­mente, Scene­Graph é um frame­work de UI basea­do em nós (nodes).
Na práti­ca, ele é:

• uma árvore de com­po­nentes visuais
• um sis­tema ori­en­ta­do a even­tos
• um con­tra­to claro entre lay­out (XML) e lóg­i­ca (BrightScript)

Scene­Graph foi cri­a­do para resolver prob­le­mas clás­si­cos de TV:

• hard­ware lim­i­ta­do
• foco via con­t­role remo­to
• play­back con­tín­uo
• esta­bil­i­dade aci­ma de tudo

Por isso ele é declar­a­ti­vo, pre­visív­el e restri­ti­vo de propósi­to.

---

A separação fundamental: XML ≠ BrightScript

Se você enten­der ape­nas uma coisa sobre Scene­Graph, que seja esta:

XML define “o que existe”
BrightScript define “o que acon­tece”

Essa sep­a­ração é o que tor­na os apps Roku:

• mais estáveis
• mais fáceis de man­ter
• menos propen­sos a crash em pro­dução

Papel do XML (estrutura e visual)

No XML você define:

• hier­ar­quia de nós
• com­po­nentes visuais (Label, Poster, Markup­Grid, Video)
• lay­out e posi­ciona­men­to
• IDs e cam­pos observáveis

O XML não decide lóg­i­ca, ape­nas declara a cena.

---

Exemplo real: Scene XML bem definido

<component name="HomeScene" extends="Scene">
  <children>
    <MarkupGrid
      id="contentGrid"
      itemSize="[400,225]"
      numRows="2"
      translation="[60,120]" />
  </children>
</component>

Esse XML já responde per­gun­tas impor­tantes:

• existe uma cena prin­ci­pal
• existe um grid
• o foco será nesse grid
• o lay­out é pre­visív­el

Nada de lóg­i­ca aqui — e isso é bom.

---

Papel do BrightScript no SceneGraph

O BrightScript entra para:

• car­regar dados
• rea­gir a even­tos
• obser­var mudanças de esta­do
• con­tro­lar nave­g­ação
• ini­ciar play­back
• tratar erros

Ele nun­ca dev­e­ria redesen­har a UI, ape­nas alter­ar esta­do e con­teú­do.

---

Exemplo prático: Scene BrightScript conectado ao XML

sub init()
    m.grid = m.top.findNode("contentGrid")
    m.grid.observeField("itemSelected", "onItemSelected")
    loadCatalog()
end sub

sub loadCatalog()
    items = ApiService_GetCatalog()
    if items = invalid then return
    m.grid.content = buildContentNode(items)
end sub

Aqui vemos o padrão cor­re­to:

• init() conec­ta a lóg­i­ca à UI
• observeField escu­ta even­tos
• dados entram como ContentNode
• nen­hu­ma manip­u­lação visu­al dire­ta

---

SceneGraph é orientado a eventos (não a comandos)

Um erro comum de quem vem do web ou mobile é ten­tar “man­dar” na UI.

No Scene­Graph:

• você obser­va
• você reage
• você altera esta­do
• a UI se atu­al­iza soz­in­ha

Exemplo clássico: seleção de item

sub onItemSelected()
    index = m.grid.itemSelected
    selectedItem = m.grid.content.getChild(index)
    navigateToPlayer(selectedItem)
end sub

O even­to acon­tece → o app reage.
Esse mod­e­lo reduz bugs e sim­pli­fi­ca raciocínio.

---

A árvore de nós (Node Tree): como pensar corretamente

Todo app Scene­Graph é uma árvore viva.

• Scene (raiz)
• Con­tain­ers
• Grids
• Posters
• Labels
• Video
• Over­lays

Boas práti­cas reais:

• reuti­lizar nós sem­pre que pos­sív­el
• evi­tar criar/destruir nós em exces­so
• man­ter a árvore pre­visív­el
• não “inflar” a cena sem neces­si­dade

Per­for­mance em Roku não é sobre GPU, é sobre orga­ni­za­ção da árvore.

---

SceneGraph + Streaming (VOD e FAST)

VOD

• usuário escol­he con­teú­do
• grid → play­er
• pausa, resume, próx­i­mo episó­dio

FAST (TV linear)

• fluxo con­tín­uo
• EPG
• tro­ca de pro­gra­mas
• ads fre­quentes
• tol­erân­cia a fal­has

Scene­Graph fun­ciona bem nos dois, des­de que:

• a lóg­i­ca de play­er seja iso­la­da
• a cena prin­ci­pal não fique “pesa­da”
• esta­dos sejam obser­va­dos cor­re­ta­mente

---

Integração com Player: estados são obrigatórios

O maior erro em apps Roku é não obser­var o esta­do do Video node.

m.video.observeField("state", "onVideoState")

sub onVideoState()
    if m.video.state = "error"
        showFallback()
    end if
end sub

Isso evi­ta:

• tela pre­ta
• trava­men­to silen­cioso
• reprovação na revisão da Roku

---

SceneGraph e performance: o que realmente importa

O que impacta per­for­mance de ver­dade:

• loops lon­gos na thread de UI
• parse de JSON gigante sem cuida­do
• cri­ação exces­si­va de nós
• ima­gens grandes sem otimiza­ção
• não tratar invalid

O que não impacta tan­to quan­to parece:

• “com­plex­i­dade” do XML
• quan­ti­dade de arquiv­os
• número de com­po­nentes (bem orga­ni­za­dos)

Orga­ni­za­ção vence micro-otimiza­ção.

---

Arquitetura recomendada (padrão profissional)

/components
  /scenes
  /ui
  /services
  /utils
source/
manifest

• Scene: coor­de­na
• UI Com­po­nents: reuti­lizáveis
• Ser­vices: API, EPG, play­back
• Utils: helpers e parsers

Isso escala para:

• VOD
• FAST
• apps white-label
• múlti­p­los canais

---

Onde SceneGraph brilha (e onde não)

Brilha quando:

• você respei­ta o mod­e­lo
• sep­a­ra bem XML e BrightScript
• pen­sa em even­tos e esta­dos
• pri­or­iza esta­bil­i­dade

Cobra seu preço quando:

• você ten­ta “imi­tar React”
• força lóg­i­ca no XML
• igno­ra esta­dos do play­er
• não tra­ta erro e rede ruim

---

Por que SceneGraph é decisivo para o sucesso do app

A Roku avalia silen­ciosa­mente:

• tem­po de ini­cial­iza­ção
• esta­bil­i­dade da UI
• com­por­ta­men­to com con­t­role remo­to
• fal­has de play­back
• con­sumo de memória

Apps que dom­i­nam Scene­Graph:

• que­bram menos
• pas­sam mais rápi­do na revisão
• escalam mel­hor
• mon­e­ti­zam com mais pre­vis­i­bil­i­dade