SystemOS Library Root and Home Game Launch
This commit is contained in:
@@ -0,0 +1,161 @@
|
||||
---
|
||||
id: AGD-0045
|
||||
ticket: system-run-cart
|
||||
title: SystemOS Library Root and Home Game Launch
|
||||
status: accepted
|
||||
created: 2026-07-03
|
||||
resolved:
|
||||
decision:
|
||||
tags: [runtime, os, hub, cartridge, launcher, library, game, architecture]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
A `DEC-0035` fechou que `system.run_cart` nao deve existir como syscall
|
||||
userland e que boot direto por host/CLI/debug deve permanecer.
|
||||
|
||||
Isso resolveu a autoridade negativa, mas ainda nao resolveu a experiencia
|
||||
desejada para o SO: apontar o runtime para um diretorio raiz de biblioteca,
|
||||
fazer a Home listar os cartuchos encontrados ali e permitir que o usuario clique
|
||||
em um jogo para carrega-lo.
|
||||
|
||||
O objetivo pratico e um "Switch feio": uma lista simples na Home, sem UX final,
|
||||
sem marketplace e sem catalogo rico, mas capaz de provar que o SO, e nao o
|
||||
guest, escolhe e carrega um cartucho a partir de uma biblioteca local.
|
||||
|
||||
## Problema
|
||||
|
||||
Hoje temos dois caminhos separados:
|
||||
|
||||
- boot direto por `--run <cart>` funciona e carrega um cartucho unico;
|
||||
- Hub/Home existe, mas mostra acoes fixas de Shell nativo e nao lista jogos de
|
||||
uma biblioteca real.
|
||||
|
||||
Sem uma biblioteca de cartuchos visivel para o SO, o usuario nao consegue
|
||||
iniciar jogos a partir da Home. Isso deixa a agenda `system-run-cart` incompleta
|
||||
do ponto de vista de produto: removemos o `run_cart` userland, mas ainda falta a
|
||||
alternativa correta, que e o SO iniciar cartuchos por acao de usuario.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- O root da biblioteca deve ser fornecido pelo host como `--games-root <dir>`.
|
||||
- O scan inicial deve cobrir subdiretorios imediatos com `manifest.json`.
|
||||
- O loader de diretorio existente deve continuar sendo a autoridade para validar
|
||||
cartucho completo; a biblioteca pode ler metadados minimos para listagem.
|
||||
- A Home pode mostrar uma lista feia/clicavel; polimento visual fica fora.
|
||||
- O clique em um Game deve iniciar `LoadCartridge` pelo firmware/SystemOS, nao
|
||||
por syscall guest.
|
||||
- V1 nao precisa tratar retorno de um Game para Home, porque isso pertence a
|
||||
`AGD-0041`.
|
||||
- `.pmc`, outros tipos de app, catalogo remoto, marketplace, icones, busca e
|
||||
metadados ricos ficam fora.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Biblioteca apenas para listagem
|
||||
|
||||
- **Abordagem:** adicionar `--games-root`, escanear manifestos e mostrar jogos
|
||||
na Home, mas sem permitir launch ainda.
|
||||
- **Pro:** baixa complexidade; prova descoberta/catalogo local.
|
||||
- **Contra:** nao entrega o objetivo principal de carregar jogo pela Home.
|
||||
- **Manutenibilidade:** boa, mas valor funcional limitado.
|
||||
|
||||
### Opcao B - Home lista biblioteca e carrega Game quando nao ha Game ativo
|
||||
|
||||
- **Abordagem:** adicionar `--games-root`, escanear cartuchos locais, renderizar
|
||||
lista simples na Home e permitir clique para carregar um Game via
|
||||
`LoadCartridge`. A primeira versao cobre Home inicial/sem Game residente.
|
||||
- **Pro:** entrega o fluxo desejado sem abrir troca completa entre jogos.
|
||||
- **Contra:** exige passar biblioteca/acao selecionada entre host, Hub,
|
||||
firmware e loader.
|
||||
- **Manutenibilidade:** boa se a fronteira ficar clara: biblioteca descobre,
|
||||
Hub escolhe, firmware carrega.
|
||||
|
||||
### Opcao C - Biblioteca mais troca completa entre jogos
|
||||
|
||||
- **Abordagem:** Home lista biblioteca e tambem permite `Game A -> Home ->
|
||||
Game B` ja no primeiro passo.
|
||||
- **Pro:** cobre a experiencia final.
|
||||
- **Contra:** mistura biblioteca com pausa, fechamento, cleanup e falha de load;
|
||||
depende de `AGD-0041` e `AGD-0044`.
|
||||
- **Manutenibilidade:** baixa para v1.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Recomendo a Opcao B.
|
||||
|
||||
O v1 deve permitir:
|
||||
|
||||
- host recebe `--games-root <dir>`;
|
||||
- o SO/Hub recebe uma lista de cartuchos descobertos;
|
||||
- a Home mostra uma lista simples/clicavel de jogos;
|
||||
- clicar em um Game carrega o cartucho via firmware `LoadCartridge`;
|
||||
- boot direto por `--run <cart>` continua separado e intacto;
|
||||
- nenhum guest/app chama `run_cart`;
|
||||
- o escopo v1 acontece na Home inicial; retorno de Game para Home fica para
|
||||
`AGD-0041`, e troca `Game A -> Home -> Game B` fica para `AGD-0044`.
|
||||
|
||||
Detalhes aceitos para v1:
|
||||
|
||||
- scan apenas de subdiretorios imediatos;
|
||||
- somente cartuchos `app_mode: Game`;
|
||||
- `.pmc` fica para futuro;
|
||||
- cartuchos invalidos sao logados e omitidos da lista;
|
||||
- o modelo interno deve ser uma entry de biblioteca expansivel, nao apenas um
|
||||
summary de UI. A entry pode manter o manifest carregado em memoria, path
|
||||
interno necessario para launch e metadados operacionais como instante de
|
||||
descoberta/instalacao. A UI v1 mostra apenas `title`, `app_id` e
|
||||
`app_version`, mas futuros metadados ingeridos pela biblioteca poderao ser
|
||||
usados pelo catalogo e pela propria UI;
|
||||
- clique carrega imediatamente, sem confirmacao;
|
||||
- falha de load volta para Home e registra log/erro.
|
||||
|
||||
Essa agenda deve produzir a alternativa correta ao `run_cart` userland: uma
|
||||
acao de sistema, iniciada pela Home, que carrega cartucho escolhido pelo usuario
|
||||
a partir de uma biblioteca local.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [x] O argumento deve se chamar `--games-root`.
|
||||
- [x] A biblioteca deve escanear apenas subdiretorios imediatos.
|
||||
- [x] A listagem v1 deve incluir apenas `app_mode: Game`.
|
||||
- [x] O scan deve logar cartuchos invalidos e omiti-los da lista.
|
||||
- [x] O Hub/SystemOS deve receber uma entry de biblioteca expansivel, capaz de
|
||||
manter o manifest carregado, path interno para launch e metadados
|
||||
operacionais como timestamp de descoberta/instalacao. A UI v1 so precisa
|
||||
mostrar `title`, `app_id` e `app_version`.
|
||||
- [x] O clique deve carregar imediatamente, sem confirmacao.
|
||||
- [x] Se um cartucho falha ao carregar, o sistema volta para Home e registra
|
||||
erro/log.
|
||||
- [x] Retorno de Game para Home nao pertence a esta agenda; fica para
|
||||
`AGD-0041`.
|
||||
- [x] O teste minimo deve provar o fluxo `games-root -> Home list -> click ->
|
||||
LoadCartridge -> GameRunning`?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
A agenda pode virar decisao quando estiver claro:
|
||||
|
||||
- nome e semantica do argumento de host para root da biblioteca;
|
||||
- escopo do scan e metadados minimos;
|
||||
- fronteira entre biblioteca, Hub, firmware e loader;
|
||||
- politica v1 para cartuchos invalidos;
|
||||
- regra v1 para launch quando nao ha Game ativo;
|
||||
- fronteira explicita com `AGD-0041` e `AGD-0044`;
|
||||
- testes minimos para discovery e launch pela Home.
|
||||
|
||||
## Discussao
|
||||
|
||||
- 2026-07-03: Agenda criada como continuacao da `DSC-0004` apos a `DEC-0035`.
|
||||
A decisao anterior removeu `run_cart` userland; esta agenda define o caminho
|
||||
correto para o SO/Home carregar jogos a partir de uma biblioteca local.
|
||||
- 2026-07-03: Respostas aceitas: usar `--games-root`, escanear apenas
|
||||
subdiretorios imediatos, listar somente Games, deixar `.pmc` e outros apps
|
||||
para depois, logar/omitir invalidos, usar summary com `title`, `app_id` e
|
||||
`app_version`, carregar imediatamente no clique, e deixar retorno para Home
|
||||
sob responsabilidade da `AGD-0041`.
|
||||
- 2026-07-03: Modelo de dados refinado: a biblioteca deve produzir entries
|
||||
expansíveis, nao somente summaries de UI. Cada entry pode manter manifest em
|
||||
memoria, path interno de launch e metadados operacionais como timestamp de
|
||||
descoberta/instalacao; a UI v1 escolhe quais campos mostrar, mas o modelo
|
||||
deve permitir que metadados futuros sejam ingeridos e usados pelo catalogo/UI.
|
||||
Reference in New Issue
Block a user