Compare commits
27
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
6ef376763c
|
||
|
|
f50a3f127f
|
||
|
|
f0f3f972ce
|
||
|
|
b2d2533acb
|
||
|
|
4b499288e2
|
||
|
|
aa3b31deb5 | ||
|
|
f784ccd774
|
||
|
|
7cced0709b
|
||
|
|
e2a5a67621
|
||
|
|
fbe4d0cac0
|
||
|
|
4c0f1cb9ad
|
||
|
|
94ffd241bd
|
||
|
|
a415c172c7
|
||
|
|
c89116b6f8
|
||
|
|
dc279fe72b
|
||
|
|
01221769cd
|
||
|
|
3cce8a2b25 | ||
|
|
de53eb5ad7
|
||
|
|
49cb16b6cb
|
||
|
|
3aec829c70
|
||
|
|
73c8246c8d
|
||
|
|
fa0a768b84
|
||
|
|
62573e9574
|
||
|
|
c814e057dc
|
||
|
|
8d719843c7
|
||
|
|
d6afa6ae6b
|
||
|
|
3df8227ebf
|
Generated
+10
@@ -1469,6 +1469,16 @@ version = "1.0.15"
|
|||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
|
checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "pbxgen-dummy-boy"
|
||||||
|
version = "0.1.0"
|
||||||
|
dependencies = [
|
||||||
|
"anyhow",
|
||||||
|
"prometeu-bytecode",
|
||||||
|
"prometeu-hal",
|
||||||
|
"serde_json",
|
||||||
|
]
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "pbxgen-stress"
|
name = "pbxgen-stress"
|
||||||
version = "0.1.0"
|
version = "0.1.0"
|
||||||
|
|||||||
@@ -8,6 +8,7 @@ members = [
|
|||||||
"crates/console/prometeu-vm",
|
"crates/console/prometeu-vm",
|
||||||
"crates/host/prometeu-host-desktop-winit",
|
"crates/host/prometeu-host-desktop-winit",
|
||||||
"crates/tools/prometeu-cli",
|
"crates/tools/prometeu-cli",
|
||||||
|
"crates/tools/pbxgen-dummy-boy",
|
||||||
"crates/tools/pbxgen-stress",
|
"crates/tools/pbxgen-stress",
|
||||||
"crates/dev/prometeu-test-support",
|
"crates/dev/prometeu-test-support",
|
||||||
"crates/dev/prometeu-layer-tests",
|
"crates/dev/prometeu-layer-tests",
|
||||||
|
|||||||
@@ -19,6 +19,6 @@ pub use assembler::{assemble, AsmError};
|
|||||||
pub use decoder::{decode_next, DecodeError};
|
pub use decoder::{decode_next, DecodeError};
|
||||||
pub use disassembler::disassemble;
|
pub use disassembler::disassemble;
|
||||||
pub use layout::{compute_function_layouts, FunctionLayout};
|
pub use layout::{compute_function_layouts, FunctionLayout};
|
||||||
pub use model::{BytecodeLoader, FunctionMeta, LoadError, SyscallDecl};
|
pub use model::{BytecodeLoader, FunctionMeta, LoadError, SyscallDecl, PBX_MAGIC};
|
||||||
pub use program_image::ProgramImage;
|
pub use program_image::ProgramImage;
|
||||||
pub use value::{string_materialization_count, HeapRef, Value};
|
pub use value::{string_materialization_count, HeapRef, Value};
|
||||||
|
|||||||
@@ -80,9 +80,11 @@ const SECTION_KIND_DEBUG: u32 = 3;
|
|||||||
const SECTION_KIND_EXPORTS: u32 = 4;
|
const SECTION_KIND_EXPORTS: u32 = 4;
|
||||||
const SECTION_KIND_SYSCALLS: u32 = 5;
|
const SECTION_KIND_SYSCALLS: u32 = 5;
|
||||||
|
|
||||||
/// Represents the final serialized format of a PBS v0 module.
|
pub const PBX_MAGIC: [u8; 4] = *b"PBX\0";
|
||||||
|
|
||||||
|
/// Represents the final serialized format of a PBX v0 module.
|
||||||
///
|
///
|
||||||
/// This structure is a pure data container for the PBS format. It does NOT
|
/// This structure is a pure data container for the PBX format. It does NOT
|
||||||
/// contain any linker-like logic (symbol resolution, patching, etc.).
|
/// contain any linker-like logic (symbol resolution, patching, etc.).
|
||||||
/// All multi-module programs must be flattened and linked by the compiler
|
/// All multi-module programs must be flattened and linked by the compiler
|
||||||
/// before being serialized into this format.
|
/// before being serialized into this format.
|
||||||
@@ -126,8 +128,8 @@ impl BytecodeModule {
|
|||||||
final_sections.push((SECTION_KIND_SYSCALLS, syscall_data));
|
final_sections.push((SECTION_KIND_SYSCALLS, syscall_data));
|
||||||
|
|
||||||
let mut out = Vec::new();
|
let mut out = Vec::new();
|
||||||
// Magic "PBS\0"
|
// Magic "PBX\0"
|
||||||
out.extend_from_slice(b"PBS\0");
|
out.extend_from_slice(&PBX_MAGIC);
|
||||||
// Version 0
|
// Version 0
|
||||||
out.extend_from_slice(&0u16.to_le_bytes());
|
out.extend_from_slice(&0u16.to_le_bytes());
|
||||||
// Endianness 0 (Little Endian), Reserved
|
// Endianness 0 (Little Endian), Reserved
|
||||||
@@ -272,8 +274,8 @@ impl BytecodeLoader {
|
|||||||
return Err(LoadError::UnexpectedEof);
|
return Err(LoadError::UnexpectedEof);
|
||||||
}
|
}
|
||||||
|
|
||||||
// Magic "PBS\0"
|
// Magic "PBX\0"
|
||||||
if &bytes[0..4] != b"PBS\0" {
|
if bytes[0..4] != PBX_MAGIC[..] {
|
||||||
return Err(LoadError::InvalidMagic);
|
return Err(LoadError::InvalidMagic);
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -708,7 +710,7 @@ mod tests {
|
|||||||
|
|
||||||
fn create_header(section_count: u32) -> Vec<u8> {
|
fn create_header(section_count: u32) -> Vec<u8> {
|
||||||
let mut h = vec![0u8; 32];
|
let mut h = vec![0u8; 32];
|
||||||
h[0..4].copy_from_slice(b"PBS\0");
|
h[0..4].copy_from_slice(&PBX_MAGIC);
|
||||||
h[4..6].copy_from_slice(&0u16.to_le_bytes()); // version
|
h[4..6].copy_from_slice(&0u16.to_le_bytes()); // version
|
||||||
h[6] = 0; // endianness
|
h[6] = 0; // endianness
|
||||||
h[8..12].copy_from_slice(§ion_count.to_le_bytes());
|
h[8..12].copy_from_slice(§ion_count.to_le_bytes());
|
||||||
@@ -727,7 +729,7 @@ mod tests {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
fn build_pbs_with_sections(sections: Vec<(u32, Vec<u8>)>) -> Vec<u8> {
|
fn build_pbx_with_sections(sections: Vec<(u32, Vec<u8>)>) -> Vec<u8> {
|
||||||
let mut data = create_header(sections.len() as u32);
|
let mut data = create_header(sections.len() as u32);
|
||||||
let mut offset = 32 + (sections.len() as u32 * 12);
|
let mut offset = 32 + (sections.len() as u32 * 12);
|
||||||
|
|
||||||
@@ -748,7 +750,7 @@ mod tests {
|
|||||||
#[test]
|
#[test]
|
||||||
fn test_invalid_magic() {
|
fn test_invalid_magic() {
|
||||||
let mut data = create_header(0);
|
let mut data = create_header(0);
|
||||||
data[0] = b'X';
|
data[0..4].copy_from_slice(b"PBS\0");
|
||||||
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidMagic));
|
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidMagic));
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -897,7 +899,7 @@ mod tests {
|
|||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn test_malformed_sysc_section_is_rejected() {
|
fn test_malformed_sysc_section_is_rejected() {
|
||||||
let data = build_pbs_with_sections(vec![(SECTION_KIND_SYSCALLS, vec![1, 0, 0])]);
|
let data = build_pbx_with_sections(vec![(SECTION_KIND_SYSCALLS, vec![1, 0, 0])]);
|
||||||
|
|
||||||
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::MalformedSection));
|
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::MalformedSection));
|
||||||
}
|
}
|
||||||
@@ -914,7 +916,7 @@ mod tests {
|
|||||||
sysc.extend_from_slice(&0u16.to_le_bytes());
|
sysc.extend_from_slice(&0u16.to_le_bytes());
|
||||||
sysc.extend_from_slice(&0u16.to_le_bytes());
|
sysc.extend_from_slice(&0u16.to_le_bytes());
|
||||||
|
|
||||||
let data = build_pbs_with_sections(vec![(SECTION_KIND_SYSCALLS, sysc)]);
|
let data = build_pbx_with_sections(vec![(SECTION_KIND_SYSCALLS, sysc)]);
|
||||||
|
|
||||||
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidUtf8));
|
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidUtf8));
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -4,7 +4,7 @@ use crate::value::Value;
|
|||||||
use std::collections::HashMap;
|
use std::collections::HashMap;
|
||||||
use std::sync::Arc;
|
use std::sync::Arc;
|
||||||
|
|
||||||
/// Represents a fully linked, executable PBS program image.
|
/// Represents a fully linked, executable PBX program image.
|
||||||
///
|
///
|
||||||
/// Under the Prometeu architecture, the ProgramImage is a "closed-world" artifact
|
/// Under the Prometeu architecture, the ProgramImage is a "closed-world" artifact
|
||||||
/// produced by the compiler. All linking, relocation, and symbol resolution
|
/// produced by the compiler. All linking, relocation, and symbol resolution
|
||||||
|
|||||||
@@ -191,10 +191,10 @@ impl GlyphAssetSlotIndex {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
const GLYPH_BANK_PALETTE_COUNT_V1: usize = 64;
|
const GLYPH_BANK_MAX_PALETTE_COUNT_V1: usize = 64;
|
||||||
const GLYPH_BANK_COLORS_PER_PALETTE: usize = 16;
|
const GLYPH_BANK_COLORS_PER_PALETTE: usize = 16;
|
||||||
const GLYPH_BANK_PALETTE_BYTES_V1: usize =
|
const GLYPH_BANK_PALETTE_BYTES_PER_PALETTE: usize =
|
||||||
GLYPH_BANK_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * size_of::<u32>();
|
GLYPH_BANK_COLORS_PER_PALETTE * size_of::<u32>();
|
||||||
|
|
||||||
/// Resident metadata for a decoded/materialized asset inside a BankPolicy.
|
/// Resident metadata for a decoded/materialized asset inside a BankPolicy.
|
||||||
#[derive(Debug)]
|
#[derive(Debug)]
|
||||||
@@ -599,7 +599,7 @@ impl AssetBridge for AssetManager {
|
|||||||
impl AssetManager {
|
impl AssetManager {
|
||||||
fn decode_glyph_bank_layout(
|
fn decode_glyph_bank_layout(
|
||||||
entry: &AssetEntry,
|
entry: &AssetEntry,
|
||||||
) -> Result<(TileSize, usize, usize, usize), String> {
|
) -> Result<(TileSize, usize, usize, usize, usize, usize), String> {
|
||||||
let meta = entry.metadata_as_glyph_bank()?;
|
let meta = entry.metadata_as_glyph_bank()?;
|
||||||
|
|
||||||
let tile_size = match meta.tile_size {
|
let tile_size = match meta.tile_size {
|
||||||
@@ -609,7 +609,8 @@ impl AssetManager {
|
|||||||
_ => return Err(format!("Invalid tile_size: {}", meta.tile_size)),
|
_ => return Err(format!("Invalid tile_size: {}", meta.tile_size)),
|
||||||
};
|
};
|
||||||
|
|
||||||
if meta.palette_count as usize != GLYPH_BANK_PALETTE_COUNT_V1 {
|
let palette_count = meta.palette_count as usize;
|
||||||
|
if !(1..=GLYPH_BANK_MAX_PALETTE_COUNT_V1).contains(&palette_count) {
|
||||||
return Err(format!("Invalid palette_count: {}", meta.palette_count));
|
return Err(format!("Invalid palette_count: {}", meta.palette_count));
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -618,12 +619,14 @@ impl AssetManager {
|
|||||||
|
|
||||||
let logical_pixels = width.checked_mul(height).ok_or("GlyphBank dimensions overflow")?;
|
let logical_pixels = width.checked_mul(height).ok_or("GlyphBank dimensions overflow")?;
|
||||||
let serialized_pixel_bytes = logical_pixels.div_ceil(2);
|
let serialized_pixel_bytes = logical_pixels.div_ceil(2);
|
||||||
|
let palette_bytes = palette_count
|
||||||
|
.checked_mul(GLYPH_BANK_PALETTE_BYTES_PER_PALETTE)
|
||||||
|
.ok_or("GlyphBank palette size overflow")?;
|
||||||
let serialized_size = serialized_pixel_bytes
|
let serialized_size = serialized_pixel_bytes
|
||||||
.checked_add(GLYPH_BANK_PALETTE_BYTES_V1)
|
.checked_add(palette_bytes)
|
||||||
.ok_or("GlyphBank serialized size overflow")?;
|
.ok_or("GlyphBank serialized size overflow")?;
|
||||||
let decoded_size = logical_pixels
|
let decoded_size =
|
||||||
.checked_add(GLYPH_BANK_PALETTE_BYTES_V1)
|
logical_pixels.checked_add(palette_bytes).ok_or("GlyphBank decoded size overflow")?;
|
||||||
.ok_or("GlyphBank decoded size overflow")?;
|
|
||||||
|
|
||||||
if entry.size != serialized_size as u64 {
|
if entry.size != serialized_size as u64 {
|
||||||
return Err(format!(
|
return Err(format!(
|
||||||
@@ -639,7 +642,7 @@ impl AssetManager {
|
|||||||
));
|
));
|
||||||
}
|
}
|
||||||
|
|
||||||
Ok((tile_size, width, height, serialized_pixel_bytes))
|
Ok((tile_size, width, height, serialized_pixel_bytes, palette_count, palette_bytes))
|
||||||
}
|
}
|
||||||
|
|
||||||
fn unpack_glyph_bank_pixels(packed_pixels: &[u8], logical_pixels: usize) -> Vec<u8> {
|
fn unpack_glyph_bank_pixels(packed_pixels: &[u8], logical_pixels: usize) -> Vec<u8> {
|
||||||
@@ -1200,19 +1203,18 @@ impl AssetManager {
|
|||||||
entry: &AssetEntry,
|
entry: &AssetEntry,
|
||||||
buffer: &[u8],
|
buffer: &[u8],
|
||||||
) -> Result<GlyphBank, String> {
|
) -> Result<GlyphBank, String> {
|
||||||
let (tile_size, width, height, packed_pixel_bytes) = Self::decode_glyph_bank_layout(entry)?;
|
let (tile_size, width, height, packed_pixel_bytes, palette_count, palette_bytes) =
|
||||||
if buffer.len() < packed_pixel_bytes + GLYPH_BANK_PALETTE_BYTES_V1 {
|
Self::decode_glyph_bank_layout(entry)?;
|
||||||
|
if buffer.len() < packed_pixel_bytes + palette_bytes {
|
||||||
return Err("Buffer too small for GLYPHBANK".to_string());
|
return Err("Buffer too small for GLYPHBANK".to_string());
|
||||||
}
|
}
|
||||||
|
|
||||||
let logical_pixels = width * height;
|
let logical_pixels = width * height;
|
||||||
let packed_pixels = &buffer[0..packed_pixel_bytes];
|
let packed_pixels = &buffer[0..packed_pixel_bytes];
|
||||||
let pixel_indices = Self::unpack_glyph_bank_pixels(packed_pixels, logical_pixels);
|
let pixel_indices = Self::unpack_glyph_bank_pixels(packed_pixels, logical_pixels);
|
||||||
let palette_data =
|
let palette_data = &buffer[packed_pixel_bytes..packed_pixel_bytes + palette_bytes];
|
||||||
&buffer[packed_pixel_bytes..packed_pixel_bytes + GLYPH_BANK_PALETTE_BYTES_V1];
|
|
||||||
|
|
||||||
let mut palettes =
|
let mut palettes = vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count];
|
||||||
[[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; GLYPH_BANK_PALETTE_COUNT_V1];
|
|
||||||
for (p, pal) in palettes.iter_mut().enumerate() {
|
for (p, pal) in palettes.iter_mut().enumerate() {
|
||||||
for (c, slot) in pal.iter_mut().enumerate() {
|
for (c, slot) in pal.iter_mut().enumerate() {
|
||||||
let offset = (p * 16 + c) * 4;
|
let offset = (p * 16 + c) * 4;
|
||||||
@@ -1232,7 +1234,8 @@ impl AssetManager {
|
|||||||
entry: &AssetEntry,
|
entry: &AssetEntry,
|
||||||
reader: &mut impl Read,
|
reader: &mut impl Read,
|
||||||
) -> Result<GlyphBank, String> {
|
) -> Result<GlyphBank, String> {
|
||||||
let (tile_size, width, height, packed_pixel_bytes) = Self::decode_glyph_bank_layout(entry)?;
|
let (tile_size, width, height, packed_pixel_bytes, palette_count, palette_bytes) =
|
||||||
|
Self::decode_glyph_bank_layout(entry)?;
|
||||||
let logical_pixels = width * height;
|
let logical_pixels = width * height;
|
||||||
let mut packed_pixels = vec![0_u8; packed_pixel_bytes];
|
let mut packed_pixels = vec![0_u8; packed_pixel_bytes];
|
||||||
reader
|
reader
|
||||||
@@ -1241,13 +1244,12 @@ impl AssetManager {
|
|||||||
|
|
||||||
let pixel_indices = Self::unpack_glyph_bank_pixels(&packed_pixels, logical_pixels);
|
let pixel_indices = Self::unpack_glyph_bank_pixels(&packed_pixels, logical_pixels);
|
||||||
|
|
||||||
let mut palette_data = [0_u8; GLYPH_BANK_PALETTE_BYTES_V1];
|
let mut palette_data = vec![0_u8; palette_bytes];
|
||||||
reader
|
reader
|
||||||
.read_exact(&mut palette_data)
|
.read_exact(&mut palette_data)
|
||||||
.map_err(|_| "Buffer too small for GLYPHBANK".to_string())?;
|
.map_err(|_| "Buffer too small for GLYPHBANK".to_string())?;
|
||||||
|
|
||||||
let mut palettes =
|
let mut palettes = vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count];
|
||||||
[[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; GLYPH_BANK_PALETTE_COUNT_V1];
|
|
||||||
for (p, pal) in palettes.iter_mut().enumerate() {
|
for (p, pal) in palettes.iter_mut().enumerate() {
|
||||||
for (c, slot) in pal.iter_mut().enumerate() {
|
for (c, slot) in pal.iter_mut().enumerate() {
|
||||||
let offset = (p * 16 + c) * 4;
|
let offset = (p * 16 + c) * 4;
|
||||||
@@ -1858,6 +1860,9 @@ impl AssetManager {
|
|||||||
self.glyph_slot_index.clear();
|
self.glyph_slot_index.clear();
|
||||||
self.sound_slots.write().unwrap().fill(None);
|
self.sound_slots.write().unwrap().fill(None);
|
||||||
self.scene_slots.write().unwrap().fill(None);
|
self.scene_slots.write().unwrap().fill(None);
|
||||||
|
self.gfx_installer.clear_glyph_banks();
|
||||||
|
self.sound_installer.clear_sound_banks();
|
||||||
|
self.scene_installer.clear_scene_banks();
|
||||||
}
|
}
|
||||||
|
|
||||||
pub fn glyph_asset_slot_index(&self) -> GlyphAssetSlotIndex {
|
pub fn glyph_asset_slot_index(&self) -> GlyphAssetSlotIndex {
|
||||||
@@ -1880,35 +1885,53 @@ mod tests {
|
|||||||
use prometeu_hal::tile::Tile;
|
use prometeu_hal::tile::Tile;
|
||||||
use prometeu_hal::tilemap::TileMap;
|
use prometeu_hal::tilemap::TileMap;
|
||||||
|
|
||||||
fn expected_glyph_payload_size(width: usize, height: usize) -> usize {
|
fn expected_glyph_payload_size(width: usize, height: usize, palette_count: usize) -> usize {
|
||||||
(width * height).div_ceil(2) + GLYPH_BANK_PALETTE_BYTES_V1
|
(width * height).div_ceil(2) + (palette_count * GLYPH_BANK_PALETTE_BYTES_PER_PALETTE)
|
||||||
}
|
}
|
||||||
|
|
||||||
fn expected_glyph_decoded_size(width: usize, height: usize) -> usize {
|
fn expected_glyph_decoded_size(width: usize, height: usize, palette_count: usize) -> usize {
|
||||||
width * height + GLYPH_BANK_PALETTE_BYTES_V1
|
width * height + (palette_count * GLYPH_BANK_PALETTE_BYTES_PER_PALETTE)
|
||||||
}
|
}
|
||||||
|
|
||||||
fn test_glyph_asset_data() -> Vec<u8> {
|
fn test_glyph_asset_data() -> Vec<u8> {
|
||||||
|
test_glyph_asset_data_with_palette_count(GLYPH_BANK_MAX_PALETTE_COUNT_V1)
|
||||||
|
}
|
||||||
|
|
||||||
|
fn test_glyph_asset_data_with_palette_count(palette_count: usize) -> Vec<u8> {
|
||||||
let mut data = vec![0x11u8; 128];
|
let mut data = vec![0x11u8; 128];
|
||||||
data.extend_from_slice(&[0u8; GLYPH_BANK_PALETTE_BYTES_V1]);
|
data.extend_from_slice(&vec![0u8; palette_count * GLYPH_BANK_PALETTE_BYTES_PER_PALETTE]);
|
||||||
data
|
data
|
||||||
}
|
}
|
||||||
|
|
||||||
fn test_glyph_asset_entry(asset_name: &str, width: usize, height: usize) -> AssetEntry {
|
fn test_glyph_asset_entry(asset_name: &str, width: usize, height: usize) -> AssetEntry {
|
||||||
|
test_glyph_asset_entry_with_palette_count(
|
||||||
|
asset_name,
|
||||||
|
width,
|
||||||
|
height,
|
||||||
|
GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
fn test_glyph_asset_entry_with_palette_count(
|
||||||
|
asset_name: &str,
|
||||||
|
width: usize,
|
||||||
|
height: usize,
|
||||||
|
palette_count: usize,
|
||||||
|
) -> AssetEntry {
|
||||||
AssetEntry {
|
AssetEntry {
|
||||||
asset_id: 0,
|
asset_id: 0,
|
||||||
asset_name: asset_name.to_string(),
|
asset_name: asset_name.to_string(),
|
||||||
bank_type: BankType::GLYPH,
|
bank_type: BankType::GLYPH,
|
||||||
offset: 0,
|
offset: 0,
|
||||||
size: expected_glyph_payload_size(width, height) as u64,
|
size: expected_glyph_payload_size(width, height, palette_count) as u64,
|
||||||
decoded_size: expected_glyph_decoded_size(width, height) as u64,
|
decoded_size: expected_glyph_decoded_size(width, height, palette_count) as u64,
|
||||||
codec: AssetCodec::None,
|
codec: AssetCodec::None,
|
||||||
metadata: serde_json::json!({
|
metadata: serde_json::json!({
|
||||||
"tile_size": 16,
|
"tile_size": 16,
|
||||||
"width": width,
|
"width": width,
|
||||||
"height": height,
|
"height": height,
|
||||||
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
|
"palette_count": palette_count,
|
||||||
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
|
"palette_authored": palette_count
|
||||||
}),
|
}),
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -2031,22 +2054,67 @@ mod tests {
|
|||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn test_decode_glyph_bank_unpacks_packed_pixels_and_reads_palette_colors() {
|
fn test_decode_glyph_bank_unpacks_packed_pixels_and_reads_palette_colors() {
|
||||||
let entry = test_glyph_asset_entry("glyphs", 2, 2);
|
let entry = test_glyph_asset_entry_with_palette_count("glyphs", 2, 2, 1);
|
||||||
let mut data = vec![0x10, 0x23];
|
let mut data = vec![0x10, 0x23];
|
||||||
data.extend_from_slice(&[0u8; GLYPH_BANK_PALETTE_BYTES_V1]);
|
data.extend_from_slice(&[0u8; GLYPH_BANK_PALETTE_BYTES_PER_PALETTE]);
|
||||||
data[2..6].copy_from_slice(&[0x12, 0x34, 0x56, 0x78]);
|
data[2..6].copy_from_slice(&[0x12, 0x34, 0x56, 0x78]);
|
||||||
|
|
||||||
let bank =
|
let bank =
|
||||||
AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("glyph decode");
|
AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("glyph decode");
|
||||||
|
|
||||||
assert_eq!(bank.pixel_indices, vec![1, 0, 2, 3]);
|
assert_eq!(bank.pixel_indices, vec![1, 0, 2, 3]);
|
||||||
|
assert_eq!(bank.palette_count(), 1);
|
||||||
assert_eq!(bank.palettes[0][0], Color::from_raw(0x12345678));
|
assert_eq!(bank.palettes[0][0], Color::from_raw(0x12345678));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_decode_glyph_bank_accepts_intermediate_palette_count() {
|
||||||
|
let entry = test_glyph_asset_entry_with_palette_count("glyphs", 16, 16, 7);
|
||||||
|
let data = test_glyph_asset_data_with_palette_count(7);
|
||||||
|
|
||||||
|
let bank =
|
||||||
|
AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("glyph decode");
|
||||||
|
|
||||||
|
assert_eq!(bank.palette_count(), 7);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_decode_glyph_bank_accepts_max_palette_count() {
|
||||||
|
let entry = test_glyph_asset_entry_with_palette_count(
|
||||||
|
"glyphs",
|
||||||
|
16,
|
||||||
|
16,
|
||||||
|
GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||||
|
);
|
||||||
|
let data = test_glyph_asset_data_with_palette_count(GLYPH_BANK_MAX_PALETTE_COUNT_V1);
|
||||||
|
|
||||||
|
let bank =
|
||||||
|
AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("glyph decode");
|
||||||
|
|
||||||
|
assert_eq!(bank.palette_count(), GLYPH_BANK_MAX_PALETTE_COUNT_V1);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_decode_glyph_bank_reader_matches_buffer_for_variable_palette_count() {
|
||||||
|
let entry = test_glyph_asset_entry_with_palette_count("glyphs", 16, 16, 3);
|
||||||
|
let data = test_glyph_asset_data_with_palette_count(3);
|
||||||
|
|
||||||
|
let from_buffer =
|
||||||
|
AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("buffer decode");
|
||||||
|
let mut reader = std::io::Cursor::new(data);
|
||||||
|
let from_reader = AssetManager::decode_glyph_bank_from_reader(&entry, &mut reader)
|
||||||
|
.expect("reader decode");
|
||||||
|
|
||||||
|
assert_eq!(from_buffer.palette_count(), from_reader.palette_count());
|
||||||
|
assert_eq!(from_buffer.pixel_indices, from_reader.pixel_indices);
|
||||||
|
assert_eq!(from_buffer.palettes, from_reader.palettes);
|
||||||
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn test_decode_glyph_bank_rejects_short_packed_buffer() {
|
fn test_decode_glyph_bank_rejects_short_packed_buffer() {
|
||||||
let entry = test_glyph_asset_entry("glyphs", 16, 16);
|
let entry = test_glyph_asset_entry("glyphs", 16, 16);
|
||||||
let data = vec![0u8; expected_glyph_payload_size(16, 16) - 1];
|
let data =
|
||||||
|
vec![0u8; expected_glyph_payload_size(16, 16, GLYPH_BANK_MAX_PALETTE_COUNT_V1) - 1];
|
||||||
|
|
||||||
let err = match AssetManager::decode_glyph_bank_from_buffer(&entry, &data) {
|
let err = match AssetManager::decode_glyph_bank_from_buffer(&entry, &data) {
|
||||||
Ok(_) => panic!("glyph decode should reject short buffer"),
|
Ok(_) => panic!("glyph decode should reject short buffer"),
|
||||||
@@ -2057,9 +2125,9 @@ mod tests {
|
|||||||
}
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn test_decode_glyph_bank_requires_palette_count_64() {
|
fn test_decode_glyph_bank_rejects_palette_count_zero() {
|
||||||
let mut entry = test_glyph_asset_entry("glyphs", 16, 16);
|
let mut entry = test_glyph_asset_entry("glyphs", 16, 16);
|
||||||
entry.metadata["palette_count"] = serde_json::json!(32);
|
entry.metadata["palette_count"] = serde_json::json!(0);
|
||||||
|
|
||||||
let err =
|
let err =
|
||||||
match AssetManager::decode_glyph_bank_from_buffer(&entry, &test_glyph_asset_data()) {
|
match AssetManager::decode_glyph_bank_from_buffer(&entry, &test_glyph_asset_data()) {
|
||||||
@@ -2067,7 +2135,67 @@ mod tests {
|
|||||||
Err(err) => err,
|
Err(err) => err,
|
||||||
};
|
};
|
||||||
|
|
||||||
assert_eq!(err, "Invalid palette_count: 32");
|
assert_eq!(err, "Invalid palette_count: 0");
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_decode_glyph_bank_rejects_palette_count_above_v1_max() {
|
||||||
|
let mut entry = test_glyph_asset_entry("glyphs", 16, 16);
|
||||||
|
entry.metadata["palette_count"] = serde_json::json!(65);
|
||||||
|
|
||||||
|
let err =
|
||||||
|
match AssetManager::decode_glyph_bank_from_buffer(&entry, &test_glyph_asset_data()) {
|
||||||
|
Ok(_) => panic!("glyph decode should reject invalid palette_count"),
|
||||||
|
Err(err) => err,
|
||||||
|
};
|
||||||
|
|
||||||
|
assert_eq!(err, "Invalid palette_count: 65");
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_decode_glyph_bank_rejects_mismatched_variable_decoded_size() {
|
||||||
|
let mut entry = test_glyph_asset_entry_with_palette_count("glyphs", 16, 16, 3);
|
||||||
|
entry.decoded_size += 1;
|
||||||
|
|
||||||
|
let err = match AssetManager::decode_glyph_bank_from_buffer(
|
||||||
|
&entry,
|
||||||
|
&test_glyph_asset_data_with_palette_count(3),
|
||||||
|
) {
|
||||||
|
Ok(_) => panic!("glyph decode should reject invalid decoded_size"),
|
||||||
|
Err(err) => err,
|
||||||
|
};
|
||||||
|
|
||||||
|
assert_eq!(
|
||||||
|
err,
|
||||||
|
format!(
|
||||||
|
"Invalid GLYPHBANK decoded_size: expected {}, got {}",
|
||||||
|
expected_glyph_decoded_size(16, 16, 3),
|
||||||
|
expected_glyph_decoded_size(16, 16, 3) + 1
|
||||||
|
)
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_decode_glyph_bank_rejects_mismatched_variable_serialized_size() {
|
||||||
|
let mut entry = test_glyph_asset_entry_with_palette_count("glyphs", 16, 16, 3);
|
||||||
|
entry.size += 1;
|
||||||
|
|
||||||
|
let err = match AssetManager::decode_glyph_bank_from_buffer(
|
||||||
|
&entry,
|
||||||
|
&test_glyph_asset_data_with_palette_count(3),
|
||||||
|
) {
|
||||||
|
Ok(_) => panic!("glyph decode should reject invalid serialized size"),
|
||||||
|
Err(err) => err,
|
||||||
|
};
|
||||||
|
|
||||||
|
assert_eq!(
|
||||||
|
err,
|
||||||
|
format!(
|
||||||
|
"Invalid GLYPHBANK serialized size: expected {}, got {}",
|
||||||
|
expected_glyph_payload_size(16, 16, 3),
|
||||||
|
expected_glyph_payload_size(16, 16, 3) + 1
|
||||||
|
)
|
||||||
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
@@ -2668,6 +2796,51 @@ mod tests {
|
|||||||
assert_eq!(am.slot_info(SlotRef::scene(4)).asset_id, Some(2));
|
assert_eq!(am.slot_info(SlotRef::scene(4)).asset_id, Some(2));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn shutdown_clears_physical_memory_bank_slots() {
|
||||||
|
let banks = Arc::new(MemoryBanks::new());
|
||||||
|
let gfx_installer = Arc::clone(&banks) as Arc<dyn GlyphBankPoolInstaller>;
|
||||||
|
let sound_installer = Arc::clone(&banks) as Arc<dyn SoundBankPoolInstaller>;
|
||||||
|
let scene_installer = Arc::clone(&banks) as Arc<dyn SceneBankPoolInstaller>;
|
||||||
|
|
||||||
|
let glyph_data = test_glyph_asset_data();
|
||||||
|
let scene = test_scene();
|
||||||
|
let scene_data = encode_scene_payload(&scene);
|
||||||
|
let glyph_entry = test_glyph_asset_entry("preload_glyphs", 16, 16);
|
||||||
|
let scene_entry = test_scene_asset_entry("preload_scene", &scene_data, &scene);
|
||||||
|
|
||||||
|
let mut payload = Vec::new();
|
||||||
|
payload.extend_from_slice(&glyph_data);
|
||||||
|
payload.extend_from_slice(&scene_data);
|
||||||
|
let mut shifted_scene_entry = scene_entry;
|
||||||
|
shifted_scene_entry.offset = glyph_data.len() as u64;
|
||||||
|
|
||||||
|
let am = AssetManager::new(
|
||||||
|
vec![],
|
||||||
|
AssetsPayloadSource::empty(),
|
||||||
|
gfx_installer,
|
||||||
|
sound_installer,
|
||||||
|
scene_installer,
|
||||||
|
);
|
||||||
|
am.initialize_for_cartridge(
|
||||||
|
vec![glyph_entry, shifted_scene_entry],
|
||||||
|
vec![PreloadEntry { asset_id: 0, slot: 0 }, PreloadEntry { asset_id: 2, slot: 0 }],
|
||||||
|
AssetsPayloadSource::from_bytes(payload),
|
||||||
|
);
|
||||||
|
|
||||||
|
assert!(banks.glyph_bank_slot(0).is_some());
|
||||||
|
assert!(banks.scene_bank_slot(0).is_some());
|
||||||
|
assert_eq!(am.slot_info(SlotRef::gfx(0)).asset_id, Some(0));
|
||||||
|
assert_eq!(am.slot_info(SlotRef::scene(0)).asset_id, Some(2));
|
||||||
|
|
||||||
|
am.shutdown();
|
||||||
|
|
||||||
|
assert!(banks.glyph_bank_slot(0).is_none());
|
||||||
|
assert!(banks.scene_bank_slot(0).is_none());
|
||||||
|
assert_eq!(am.slot_info(SlotRef::gfx(0)).asset_id, None);
|
||||||
|
assert_eq!(am.slot_info(SlotRef::scene(0)).asset_id, None);
|
||||||
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn test_load_returns_asset_not_found() {
|
fn test_load_returns_asset_not_found() {
|
||||||
let banks = Arc::new(MemoryBanks::new());
|
let banks = Arc::new(MemoryBanks::new());
|
||||||
|
|||||||
@@ -557,8 +557,9 @@ mod tests {
|
|||||||
|
|
||||||
fn make_glyph_bank(tile_size: TileSize, palette_id: u8, color: Color) -> GlyphBank {
|
fn make_glyph_bank(tile_size: TileSize, palette_id: u8, color: Color) -> GlyphBank {
|
||||||
let size = tile_size as usize;
|
let size = tile_size as usize;
|
||||||
let mut bank = GlyphBank::new(tile_size, size, size);
|
let mut bank =
|
||||||
bank.palettes[palette_id as usize][1] = color;
|
GlyphBank::with_palette_count(tile_size, size, size, palette_id as usize + 1);
|
||||||
|
bank.palette_mut(palette_id).unwrap()[1] = color;
|
||||||
for pixel in &mut bank.pixel_indices {
|
for pixel in &mut bank.pixel_indices {
|
||||||
*pixel = 1;
|
*pixel = 1;
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -812,7 +812,14 @@ impl Gfx {
|
|||||||
let fetch_x = if tile.entry.flip_x() { size - 1 - local_x } else { local_x };
|
let fetch_x = if tile.entry.flip_x() { size - 1 - local_x } else { local_x };
|
||||||
let fetch_y = if tile.entry.flip_y() { size - 1 - local_y } else { local_y };
|
let fetch_y = if tile.entry.flip_y() { size - 1 - local_y } else { local_y };
|
||||||
let px_index = tile.bank.get_pixel_index(tile.entry.glyph_id, fetch_x, fetch_y);
|
let px_index = tile.bank.get_pixel_index(tile.entry.glyph_id, fetch_x, fetch_y);
|
||||||
let color = tile.bank.resolve_color(tile.entry.palette_id, px_index);
|
let color = tile.bank.resolve_color(tile.entry.palette_id, px_index).unwrap_or_else(
|
||||||
|
|| {
|
||||||
|
panic!(
|
||||||
|
"SCENE composition fatal: palette_id {} is not resident for glyph asset {}",
|
||||||
|
tile.entry.palette_id, tile.entry.glyph_asset_id
|
||||||
|
)
|
||||||
|
},
|
||||||
|
);
|
||||||
if color.alpha() == 0 {
|
if color.alpha() == 0 {
|
||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
@@ -862,7 +869,14 @@ impl Gfx {
|
|||||||
let fetch_y = if sprite.flip_y { size - 1 - local_y } else { local_y };
|
let fetch_y = if sprite.flip_y { size - 1 - local_y } else { local_y };
|
||||||
|
|
||||||
let px_index = bank.get_pixel_index(sprite.glyph.glyph_id, fetch_x, fetch_y);
|
let px_index = bank.get_pixel_index(sprite.glyph.glyph_id, fetch_x, fetch_y);
|
||||||
let color = bank.resolve_color(sprite.glyph.palette_id, px_index);
|
let color = bank.resolve_color(sprite.glyph.palette_id, px_index).unwrap_or_else(
|
||||||
|
|| {
|
||||||
|
panic!(
|
||||||
|
"SPRITE composition fatal: palette_id {} is not resident for glyph bank {}",
|
||||||
|
sprite.glyph.palette_id, sprite.bank_id
|
||||||
|
)
|
||||||
|
},
|
||||||
|
);
|
||||||
if color.alpha() == 0 {
|
if color.alpha() == 0 {
|
||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
@@ -1010,9 +1024,14 @@ mod tests {
|
|||||||
|
|
||||||
fn make_glyph_bank(tile_size: TileSize, palette_colors: &[(u8, u8, Color)]) -> GlyphBank {
|
fn make_glyph_bank(tile_size: TileSize, palette_colors: &[(u8, u8, Color)]) -> GlyphBank {
|
||||||
let size = tile_size as usize;
|
let size = tile_size as usize;
|
||||||
let mut bank = GlyphBank::new(tile_size, size, size);
|
let palette_count = palette_colors
|
||||||
|
.iter()
|
||||||
|
.map(|(palette_id, _, _)| *palette_id as usize + 1)
|
||||||
|
.max()
|
||||||
|
.unwrap_or(1);
|
||||||
|
let mut bank = GlyphBank::with_palette_count(tile_size, size, size, palette_count);
|
||||||
for (palette_id, color_index, color) in palette_colors {
|
for (palette_id, color_index, color) in palette_colors {
|
||||||
bank.palettes[*palette_id as usize][*color_index as usize] = *color;
|
bank.palette_mut(*palette_id).unwrap()[*color_index as usize] = *color;
|
||||||
}
|
}
|
||||||
bank
|
bank
|
||||||
}
|
}
|
||||||
@@ -1152,6 +1171,26 @@ mod tests {
|
|||||||
assert_eq!(back[0], Color::RED.raw());
|
assert_eq!(back[0], Color::RED.raw());
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
#[should_panic(expected = "SPRITE composition fatal: palette_id 1 is not resident")]
|
||||||
|
fn sprite_draw_panics_for_invalid_palette_reference() {
|
||||||
|
let bank = make_filled_glyph_bank(TileSize::Size8, 0, &[(0, 0, Color::GREEN)]);
|
||||||
|
let mut back = vec![Color::BLACK.raw(); 8 * 8];
|
||||||
|
let sprite = Sprite {
|
||||||
|
glyph: Glyph { glyph_id: 0, palette_id: 1 },
|
||||||
|
x: 0,
|
||||||
|
y: 0,
|
||||||
|
layer: 0,
|
||||||
|
flip_x: false,
|
||||||
|
flip_y: false,
|
||||||
|
bank_id: 0,
|
||||||
|
active: true,
|
||||||
|
priority: 0,
|
||||||
|
};
|
||||||
|
|
||||||
|
Gfx::draw_sprite_pixel_by_pixel(&mut back, 8, 8, &sprite, &bank);
|
||||||
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn test_cached_tile_draws_opaque_color_index_zero() {
|
fn test_cached_tile_draws_opaque_color_index_zero() {
|
||||||
let bank = make_filled_glyph_bank(TileSize::Size8, 0, &[(0, 0, Color::GREEN)]);
|
let bank = make_filled_glyph_bank(TileSize::Size8, 0, &[(0, 0, Color::GREEN)]);
|
||||||
@@ -1194,6 +1233,26 @@ mod tests {
|
|||||||
assert_eq!(target.back[0], Color::RED.raw());
|
assert_eq!(target.back[0], Color::RED.raw());
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
#[should_panic(expected = "SCENE composition fatal: palette_id 1 is not resident")]
|
||||||
|
fn cached_tile_draw_panics_for_invalid_palette_reference() {
|
||||||
|
let bank = make_filled_glyph_bank(TileSize::Size8, 0, &[(0, 0, Color::GREEN)]);
|
||||||
|
let mut back = vec![Color::BLACK.raw(); 8 * 8];
|
||||||
|
let mut target = RenderTarget { back: &mut back, screen_w: 8, screen_h: 8 };
|
||||||
|
let entry = CachedTileEntry {
|
||||||
|
active: true,
|
||||||
|
glyph_id: 0,
|
||||||
|
palette_id: 1,
|
||||||
|
flags: 0,
|
||||||
|
glyph_asset_id: 0,
|
||||||
|
};
|
||||||
|
|
||||||
|
Gfx::draw_cached_tile_pixels(
|
||||||
|
&mut target,
|
||||||
|
CachedTileDraw { x: 0, y: 0, entry, bank: &bank, tile_size: TileSize::Size8 },
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn test_draw_rect() {
|
fn test_draw_rect() {
|
||||||
let banks = Arc::new(MemoryBanks::new());
|
let banks = Arc::new(MemoryBanks::new());
|
||||||
|
|||||||
@@ -118,7 +118,11 @@ impl Game2DFrameComposer for Hardware {
|
|||||||
}
|
}
|
||||||
|
|
||||||
fn emit_sprite(&mut self, sprite: Sprite) -> prometeu_hal::ComposerOpStatus {
|
fn emit_sprite(&mut self, sprite: Sprite) -> prometeu_hal::ComposerOpStatus {
|
||||||
if self.gfx.glyph_banks.glyph_bank_slot(sprite.bank_id as usize).is_none() {
|
let Some(bank) = self.gfx.glyph_banks.glyph_bank_slot(sprite.bank_id as usize) else {
|
||||||
|
return prometeu_hal::ComposerOpStatus::BankInvalid;
|
||||||
|
};
|
||||||
|
|
||||||
|
if !bank.contains_palette(sprite.glyph.palette_id) {
|
||||||
return prometeu_hal::ComposerOpStatus::BankInvalid;
|
return prometeu_hal::ComposerOpStatus::BankInvalid;
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -261,7 +265,7 @@ mod tests {
|
|||||||
|
|
||||||
fn make_glyph_bank() -> GlyphBank {
|
fn make_glyph_bank() -> GlyphBank {
|
||||||
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
|
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
|
||||||
bank.palettes[0][1] = Color::RED;
|
bank.palette_mut(0).unwrap()[1] = Color::RED;
|
||||||
for pixel in &mut bank.pixel_indices {
|
for pixel in &mut bank.pixel_indices {
|
||||||
*pixel = 1;
|
*pixel = 1;
|
||||||
}
|
}
|
||||||
@@ -433,4 +437,28 @@ mod tests {
|
|||||||
|
|
||||||
assert_eq!(hardware.gfx.front_buffer()[0], Color::RED.raw());
|
assert_eq!(hardware.gfx.front_buffer()[0], Color::RED.raw());
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn emit_sprite_rejects_palette_id_outside_loaded_glyph_bank() {
|
||||||
|
let banks = Arc::new(MemoryBanks::new());
|
||||||
|
banks.install_glyph_bank(0, Arc::new(make_glyph_bank()));
|
||||||
|
let mut hardware = Hardware::new_with_memory_banks(banks);
|
||||||
|
|
||||||
|
let status = Game2DFrameComposer::emit_sprite(
|
||||||
|
&mut hardware,
|
||||||
|
Sprite {
|
||||||
|
glyph: Glyph { glyph_id: 0, palette_id: 1 },
|
||||||
|
x: 0,
|
||||||
|
y: 0,
|
||||||
|
layer: 0,
|
||||||
|
bank_id: 0,
|
||||||
|
active: false,
|
||||||
|
flip_x: false,
|
||||||
|
flip_y: false,
|
||||||
|
priority: 0,
|
||||||
|
},
|
||||||
|
);
|
||||||
|
|
||||||
|
assert_eq!(status, prometeu_hal::ComposerOpStatus::BankInvalid);
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -24,6 +24,8 @@ pub trait GlyphBankPoolAccess: Send + Sync {
|
|||||||
pub trait GlyphBankPoolInstaller: Send + Sync {
|
pub trait GlyphBankPoolInstaller: Send + Sync {
|
||||||
/// Atomically swaps the resident GlyphBank in the specified slot.
|
/// Atomically swaps the resident GlyphBank in the specified slot.
|
||||||
fn install_glyph_bank(&self, slot: usize, bank: Arc<GlyphBank>);
|
fn install_glyph_bank(&self, slot: usize, bank: Arc<GlyphBank>);
|
||||||
|
/// Clears all resident GlyphBank slots.
|
||||||
|
fn clear_glyph_banks(&self);
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Non-generic interface for peripherals to access sound banks.
|
/// Non-generic interface for peripherals to access sound banks.
|
||||||
@@ -38,6 +40,8 @@ pub trait SoundBankPoolAccess: Send + Sync {
|
|||||||
pub trait SoundBankPoolInstaller: Send + Sync {
|
pub trait SoundBankPoolInstaller: Send + Sync {
|
||||||
/// Atomically swaps the resident SoundBank in the specified slot.
|
/// Atomically swaps the resident SoundBank in the specified slot.
|
||||||
fn install_sound_bank(&self, slot: usize, bank: Arc<SoundBank>);
|
fn install_sound_bank(&self, slot: usize, bank: Arc<SoundBank>);
|
||||||
|
/// Clears all resident SoundBank slots.
|
||||||
|
fn clear_sound_banks(&self);
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Non-generic interface for peripherals to access scene banks.
|
/// Non-generic interface for peripherals to access scene banks.
|
||||||
@@ -52,6 +56,8 @@ pub trait SceneBankPoolAccess: Send + Sync {
|
|||||||
pub trait SceneBankPoolInstaller: Send + Sync {
|
pub trait SceneBankPoolInstaller: Send + Sync {
|
||||||
/// Atomically swaps the resident SceneBank in the specified slot.
|
/// Atomically swaps the resident SceneBank in the specified slot.
|
||||||
fn install_scene_bank(&self, slot: usize, bank: Arc<SceneBank>);
|
fn install_scene_bank(&self, slot: usize, bank: Arc<SceneBank>);
|
||||||
|
/// Clears all resident SceneBank slots.
|
||||||
|
fn clear_scene_banks(&self);
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Centralized container for all hardware memory banks.
|
/// Centralized container for all hardware memory banks.
|
||||||
@@ -100,6 +106,10 @@ impl GlyphBankPoolInstaller for MemoryBanks {
|
|||||||
pool[slot] = Some(bank);
|
pool[slot] = Some(bank);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
fn clear_glyph_banks(&self) {
|
||||||
|
self.glyph_bank_pool.write().unwrap().fill(None);
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
impl SoundBankPoolAccess for MemoryBanks {
|
impl SoundBankPoolAccess for MemoryBanks {
|
||||||
@@ -120,6 +130,10 @@ impl SoundBankPoolInstaller for MemoryBanks {
|
|||||||
pool[slot] = Some(bank);
|
pool[slot] = Some(bank);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
fn clear_sound_banks(&self) {
|
||||||
|
self.sound_bank_pool.write().unwrap().fill(None);
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
impl SceneBankPoolAccess for MemoryBanks {
|
impl SceneBankPoolAccess for MemoryBanks {
|
||||||
@@ -140,6 +154,10 @@ impl SceneBankPoolInstaller for MemoryBanks {
|
|||||||
pool[slot] = Some(bank);
|
pool[slot] = Some(bank);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
fn clear_scene_banks(&self) {
|
||||||
|
self.scene_bank_pool.write().unwrap().fill(None);
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
impl HalRenderResourceAccess for MemoryBanks {
|
impl HalRenderResourceAccess for MemoryBanks {
|
||||||
@@ -178,7 +196,7 @@ mod tests {
|
|||||||
|
|
||||||
fn make_glyph_bank() -> GlyphBank {
|
fn make_glyph_bank() -> GlyphBank {
|
||||||
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
|
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
|
||||||
bank.palettes[0][1] = Color::WHITE;
|
bank.palette_mut(0).unwrap()[1] = Color::WHITE;
|
||||||
bank
|
bank
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -250,21 +250,24 @@ impl Firmware {
|
|||||||
mod tests {
|
mod tests {
|
||||||
use super::*;
|
use super::*;
|
||||||
use crate::firmware::firmware_state::HubHomeStep;
|
use crate::firmware::firmware_state::HubHomeStep;
|
||||||
|
use crate::firmware::resident_game_termination::{self, ResidentGameTerminationOutcome};
|
||||||
use prometeu_bytecode::assembler::assemble;
|
use prometeu_bytecode::assembler::assemble;
|
||||||
use prometeu_bytecode::model::{BytecodeModule, FunctionMeta, SyscallDecl};
|
use prometeu_bytecode::model::{BytecodeModule, FunctionMeta, SyscallDecl};
|
||||||
use prometeu_drivers::TestPlatform;
|
use prometeu_drivers::{GlyphBankPoolAccess, SceneBankPoolAccess, TestPlatform};
|
||||||
use prometeu_hal::RuntimePlatform;
|
use prometeu_hal::RuntimePlatform;
|
||||||
use prometeu_hal::app_mode::AppMode;
|
use prometeu_hal::app_mode::AppMode;
|
||||||
|
use prometeu_hal::asset::{BankType, SlotRef};
|
||||||
use prometeu_hal::cartridge::AssetsPayloadSource;
|
use prometeu_hal::cartridge::AssetsPayloadSource;
|
||||||
use prometeu_hal::color::Color;
|
use prometeu_hal::color::Color;
|
||||||
|
use prometeu_hal::log::{LogLevel, LogSource};
|
||||||
use prometeu_hal::primitives::Rect;
|
use prometeu_hal::primitives::Rect;
|
||||||
use prometeu_hal::syscalls::{Syscall, caps};
|
use prometeu_hal::syscalls::{Syscall, caps};
|
||||||
use prometeu_system::process::ProcessState;
|
use prometeu_system::process::ProcessState;
|
||||||
use prometeu_system::task::{TaskId, TaskState};
|
use prometeu_system::task::{TaskId, TaskState};
|
||||||
use prometeu_system::windows::WindowOwner;
|
use prometeu_system::windows::WindowOwner;
|
||||||
use prometeu_system::{
|
use prometeu_system::{
|
||||||
CrashReport, ForegroundOwner, GameLifecycleEventKind, ResidentGameState,
|
CrashReport, ForegroundOwner, GameLifecycleEventKind, HUB_SUSPENDED_GAME_KILL_CONTROL,
|
||||||
discover_games_root,
|
ResidentGameState, discover_games_root,
|
||||||
};
|
};
|
||||||
use std::fs;
|
use std::fs;
|
||||||
use std::path::PathBuf;
|
use std::path::PathBuf;
|
||||||
@@ -299,6 +302,18 @@ mod tests {
|
|||||||
title: &str,
|
title: &str,
|
||||||
app_version: &str,
|
app_version: &str,
|
||||||
with_program: bool,
|
with_program: bool,
|
||||||
|
) -> PathBuf {
|
||||||
|
let program = with_program.then(halting_program);
|
||||||
|
self.add_game_with_program(name, app_id, title, app_version, program)
|
||||||
|
}
|
||||||
|
|
||||||
|
fn add_game_with_program(
|
||||||
|
&self,
|
||||||
|
name: &str,
|
||||||
|
app_id: u32,
|
||||||
|
title: &str,
|
||||||
|
app_version: &str,
|
||||||
|
program: Option<Vec<u8>>,
|
||||||
) -> PathBuf {
|
) -> PathBuf {
|
||||||
let cart = self.path.join(name);
|
let cart = self.path.join(name);
|
||||||
fs::create_dir_all(&cart).expect("test cartridge should be created");
|
fs::create_dir_all(&cart).expect("test cartridge should be created");
|
||||||
@@ -314,8 +329,8 @@ mod tests {
|
|||||||
);
|
);
|
||||||
fs::write(cart.join("manifest.json"), manifest)
|
fs::write(cart.join("manifest.json"), manifest)
|
||||||
.expect("test manifest should be written");
|
.expect("test manifest should be written");
|
||||||
if with_program {
|
if let Some(program) = program {
|
||||||
fs::write(cart.join("program.pbx"), halting_program())
|
fs::write(cart.join("program.pbx"), program)
|
||||||
.expect("test program should be written");
|
.expect("test program should be written");
|
||||||
}
|
}
|
||||||
cart
|
cart
|
||||||
@@ -346,6 +361,10 @@ mod tests {
|
|||||||
.serialize()
|
.serialize()
|
||||||
}
|
}
|
||||||
|
|
||||||
|
fn repository_test_cartridges_root() -> PathBuf {
|
||||||
|
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../..").join("test-cartridges")
|
||||||
|
}
|
||||||
|
|
||||||
fn invalid_game_cartridge() -> Cartridge {
|
fn invalid_game_cartridge() -> Cartridge {
|
||||||
Cartridge {
|
Cartridge {
|
||||||
app_id: 7,
|
app_id: 7,
|
||||||
@@ -460,6 +479,12 @@ mod tests {
|
|||||||
windows.set_focus(id);
|
windows.set_focus(id);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
fn front_buffer_pixel(platform: &TestPlatform, x: i32, y: i32) -> u32 {
|
||||||
|
const FRAMEBUFFER_WIDTH: usize = 480;
|
||||||
|
let index = x as usize + y as usize * FRAMEBUFFER_WIDTH;
|
||||||
|
platform.local_hardware().gfx.front_buffer()[index]
|
||||||
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn load_cartridge_transitions_to_app_crashes_when_vm_init_fails() {
|
fn load_cartridge_transitions_to_app_crashes_when_vm_init_fails() {
|
||||||
let mut firmware = Firmware::new(None);
|
let mut firmware = Firmware::new(None);
|
||||||
@@ -807,6 +832,433 @@ mod tests {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn repository_stress_to_dummy_boy_switch_is_end_to_end() {
|
||||||
|
let library = discover_games_root(repository_test_cartridges_root());
|
||||||
|
assert!(
|
||||||
|
library
|
||||||
|
.entries()
|
||||||
|
.iter()
|
||||||
|
.any(|entry| entry.app_id == 1 && entry.title == "Stress Console")
|
||||||
|
);
|
||||||
|
assert!(
|
||||||
|
library.entries().iter().any(|entry| entry.app_id == 2 && entry.title == "Dummy Boy")
|
||||||
|
);
|
||||||
|
|
||||||
|
let (mut firmware, mut platform) = hub_home_firmware();
|
||||||
|
firmware.hub.set_game_library(library);
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
let stress_click =
|
||||||
|
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
|
||||||
|
firmware.tick(&stress_click, &mut platform);
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
let stress_task = match &firmware.state {
|
||||||
|
FirmwareState::GameRunning(step) => step.task_id,
|
||||||
|
other => panic!("expected Stress GameRunning state, got {:?}", other),
|
||||||
|
};
|
||||||
|
assert_eq!(firmware.os.vm().current_app_id(), 1);
|
||||||
|
assert_eq!(firmware.os.vm().current_cartridge_title(), "Stress Console");
|
||||||
|
assert_eq!(
|
||||||
|
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
|
||||||
|
Some(100)
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
|
||||||
|
Some(1)
|
||||||
|
);
|
||||||
|
|
||||||
|
firmware.request_home_from_host();
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
let hub_ownership = firmware.os.vm().active_render_ownership();
|
||||||
|
assert_eq!(hub_ownership.app_mode, AppMode::Shell);
|
||||||
|
assert_eq!(hub_ownership.app_id, 0);
|
||||||
|
assert_eq!(
|
||||||
|
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
|
||||||
|
Some(100)
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
|
||||||
|
Some(1)
|
||||||
|
);
|
||||||
|
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
let dummy_click =
|
||||||
|
InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() };
|
||||||
|
firmware.tick(&dummy_click, &mut platform);
|
||||||
|
assert_eq!(
|
||||||
|
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
|
||||||
|
None
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
|
||||||
|
None
|
||||||
|
);
|
||||||
|
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_none());
|
||||||
|
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_none());
|
||||||
|
|
||||||
|
assert_eq!(firmware.os.lifecycle().task_state(stress_task), Some(TaskState::Closed));
|
||||||
|
assert_eq!(
|
||||||
|
firmware.os.lifecycle().process_state_for_task(stress_task),
|
||||||
|
Ok(ProcessState::Stopped)
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
firmware.os.sessions().vm_session_for_task(stress_task).map(|session| session.task_id),
|
||||||
|
None
|
||||||
|
);
|
||||||
|
|
||||||
|
let dummy_task = firmware
|
||||||
|
.os
|
||||||
|
.lifecycle()
|
||||||
|
.resident_game_task()
|
||||||
|
.expect("Dummy Boy should be resident after switch load");
|
||||||
|
assert_ne!(dummy_task, stress_task);
|
||||||
|
assert_eq!(
|
||||||
|
firmware.os.sessions().vm_session_for_task(dummy_task).map(|session| {
|
||||||
|
(session.app_id, session.title.clone(), session.app_version.clone())
|
||||||
|
}),
|
||||||
|
Some((2, "Dummy Boy".to_string(), "0.1.0".to_string()))
|
||||||
|
);
|
||||||
|
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
match &firmware.state {
|
||||||
|
FirmwareState::GameRunning(step) => assert_eq!(step.task_id, dummy_task),
|
||||||
|
other => panic!("expected Dummy Boy GameRunning state, got {:?}", other),
|
||||||
|
}
|
||||||
|
assert_eq!(firmware.os.lifecycle().foreground_owner(), ForegroundOwner::Game(dummy_task));
|
||||||
|
assert_eq!(firmware.os.vm().current_app_id(), 2);
|
||||||
|
assert_eq!(firmware.os.vm().current_cartridge_title(), "Dummy Boy");
|
||||||
|
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
let dummy_ownership = firmware.os.vm().active_render_ownership();
|
||||||
|
assert_eq!(dummy_ownership.app_mode, AppMode::Game);
|
||||||
|
assert_eq!(dummy_ownership.app_id, 2);
|
||||||
|
|
||||||
|
let front = platform.local_hardware().gfx.front_buffer();
|
||||||
|
let center = 240 + 135 * 480;
|
||||||
|
assert_eq!(front[center], Color::GREEN.raw());
|
||||||
|
|
||||||
|
firmware.request_home_from_host();
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
let hub_ownership = firmware.os.vm().active_render_ownership();
|
||||||
|
assert_eq!(hub_ownership.app_mode, AppMode::Shell);
|
||||||
|
assert_eq!(hub_ownership.app_id, 0);
|
||||||
|
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
let stress_click =
|
||||||
|
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
|
||||||
|
firmware.tick(&stress_click, &mut platform);
|
||||||
|
|
||||||
|
assert_eq!(firmware.os.lifecycle().task_state(dummy_task), Some(TaskState::Closed));
|
||||||
|
assert_eq!(
|
||||||
|
firmware.os.lifecycle().process_state_for_task(dummy_task),
|
||||||
|
Ok(ProcessState::Stopped)
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
firmware.os.sessions().vm_session_for_task(dummy_task).map(|session| session.task_id),
|
||||||
|
None
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
|
||||||
|
Some(100)
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
|
||||||
|
Some(1)
|
||||||
|
);
|
||||||
|
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_some());
|
||||||
|
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_some());
|
||||||
|
|
||||||
|
let second_stress_task = firmware
|
||||||
|
.os
|
||||||
|
.lifecycle()
|
||||||
|
.resident_game_task()
|
||||||
|
.expect("Stress should be resident after switching back");
|
||||||
|
assert_ne!(second_stress_task, stress_task);
|
||||||
|
assert_ne!(second_stress_task, dummy_task);
|
||||||
|
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
match &firmware.state {
|
||||||
|
FirmwareState::GameRunning(step) => assert_eq!(step.task_id, second_stress_task),
|
||||||
|
other => panic!("expected second Stress GameRunning state, got {:?}", other),
|
||||||
|
}
|
||||||
|
assert_eq!(firmware.os.vm().current_app_id(), 1);
|
||||||
|
assert_eq!(firmware.os.vm().current_cartridge_title(), "Stress Console");
|
||||||
|
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
let stress_ownership = firmware.os.vm().active_render_ownership();
|
||||||
|
assert_eq!(stress_ownership.app_mode, AppMode::Game);
|
||||||
|
assert_eq!(stress_ownership.app_id, 1);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn resident_game_termination_noops_when_no_game_is_resident() {
|
||||||
|
let (mut firmware, mut platform) = hub_home_firmware();
|
||||||
|
let ownership_before = firmware.os.vm().active_render_ownership();
|
||||||
|
|
||||||
|
let outcome = resident_game_termination::terminate_resident_game(
|
||||||
|
&mut firmware.os,
|
||||||
|
&mut platform,
|
||||||
|
true,
|
||||||
|
)
|
||||||
|
.expect("no resident game termination should not fail");
|
||||||
|
|
||||||
|
assert_eq!(outcome, ResidentGameTerminationOutcome::NoResidentGame);
|
||||||
|
assert_eq!(firmware.os.vm().active_render_ownership(), ownership_before);
|
||||||
|
assert_eq!(firmware.os.lifecycle().resident_game_task(), None);
|
||||||
|
assert!(
|
||||||
|
!firmware
|
||||||
|
.os
|
||||||
|
.recent_logs(16)
|
||||||
|
.iter()
|
||||||
|
.any(|event| event.msg.contains("Resident game killed from Hub"))
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn resident_game_termination_closes_session_and_cleans_runtime_state() {
|
||||||
|
let library = discover_games_root(repository_test_cartridges_root());
|
||||||
|
let (mut firmware, mut platform) = hub_home_firmware();
|
||||||
|
firmware.hub.set_game_library(library);
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
let stress_click =
|
||||||
|
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
|
||||||
|
firmware.tick(&stress_click, &mut platform);
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
let stress_task = match &firmware.state {
|
||||||
|
FirmwareState::GameRunning(step) => step.task_id,
|
||||||
|
other => panic!("expected Stress GameRunning state, got {:?}", other),
|
||||||
|
};
|
||||||
|
|
||||||
|
firmware.request_home_from_host();
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
|
||||||
|
assert_eq!(firmware.os.lifecycle().resident_game_task(), Some(stress_task));
|
||||||
|
assert!(firmware.game_lifecycle_audio_paused());
|
||||||
|
assert_eq!(
|
||||||
|
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
|
||||||
|
Some(100)
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
|
||||||
|
Some(1)
|
||||||
|
);
|
||||||
|
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_some());
|
||||||
|
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_some());
|
||||||
|
|
||||||
|
let outcome = resident_game_termination::terminate_resident_game(
|
||||||
|
&mut firmware.os,
|
||||||
|
&mut platform,
|
||||||
|
true,
|
||||||
|
)
|
||||||
|
.expect("resident game termination should succeed");
|
||||||
|
|
||||||
|
assert_eq!(
|
||||||
|
outcome,
|
||||||
|
ResidentGameTerminationOutcome::Terminated {
|
||||||
|
task_id: stress_task,
|
||||||
|
title: "Stress Console".to_string()
|
||||||
|
}
|
||||||
|
);
|
||||||
|
assert_eq!(firmware.os.lifecycle().resident_game_task(), None);
|
||||||
|
assert_eq!(firmware.os.lifecycle().task_state(stress_task), Some(TaskState::Closed));
|
||||||
|
assert_eq!(
|
||||||
|
firmware.os.lifecycle().process_state_for_task(stress_task),
|
||||||
|
Ok(ProcessState::Stopped)
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
firmware.os.sessions().vm_session_for_task(stress_task).map(|session| session.task_id),
|
||||||
|
None
|
||||||
|
);
|
||||||
|
assert!(!firmware.game_lifecycle_audio_paused());
|
||||||
|
|
||||||
|
let ownership = firmware.os.vm().active_render_ownership();
|
||||||
|
assert_eq!(ownership.app_mode, AppMode::Shell);
|
||||||
|
assert_eq!(ownership.app_id, 0);
|
||||||
|
assert_eq!(platform.local_hardware().frame_composer.active_scene_id(), None);
|
||||||
|
assert_eq!(
|
||||||
|
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
|
||||||
|
None
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
|
||||||
|
None
|
||||||
|
);
|
||||||
|
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_none());
|
||||||
|
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_none());
|
||||||
|
|
||||||
|
assert!(
|
||||||
|
firmware.os.recent_logs(32).iter().any(|event| {
|
||||||
|
event.level == LogLevel::Info
|
||||||
|
&& event.source == LogSource::Hub
|
||||||
|
&& event.msg == "Resident game killed from Hub: Stress Console"
|
||||||
|
}),
|
||||||
|
"manual Hub kill should emit an INFO log"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn hub_kill_control_click_terminates_resident_game_and_stays_home() {
|
||||||
|
let library = discover_games_root(repository_test_cartridges_root());
|
||||||
|
let (mut firmware, mut platform) = hub_home_firmware();
|
||||||
|
firmware.hub.set_game_library(library);
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
let stress_click =
|
||||||
|
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
|
||||||
|
firmware.tick(&stress_click, &mut platform);
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
let stress_task = match &firmware.state {
|
||||||
|
FirmwareState::GameRunning(step) => step.task_id,
|
||||||
|
other => panic!("expected Stress GameRunning state, got {:?}", other),
|
||||||
|
};
|
||||||
|
|
||||||
|
firmware.request_home_from_host();
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
|
||||||
|
assert_eq!(firmware.os.lifecycle().resident_game_task(), Some(stress_task));
|
||||||
|
|
||||||
|
let kill_sample_x = HUB_SUSPENDED_GAME_KILL_CONTROL.x + 2;
|
||||||
|
let kill_sample_y = HUB_SUSPENDED_GAME_KILL_CONTROL.y + 2;
|
||||||
|
assert_eq!(
|
||||||
|
front_buffer_pixel(&platform, kill_sample_x, kill_sample_y),
|
||||||
|
Color::rgb(164, 32, 40).raw(),
|
||||||
|
"Hub should render the suspended-game kill control before click"
|
||||||
|
);
|
||||||
|
|
||||||
|
let kill_click = InputSignals {
|
||||||
|
f_signal: true,
|
||||||
|
x_pos: HUB_SUSPENDED_GAME_KILL_CONTROL.x,
|
||||||
|
y_pos: HUB_SUSPENDED_GAME_KILL_CONTROL.y,
|
||||||
|
..Default::default()
|
||||||
|
};
|
||||||
|
firmware.tick(&kill_click, &mut platform);
|
||||||
|
|
||||||
|
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
|
||||||
|
assert_eq!(firmware.os.lifecycle().foreground_owner(), ForegroundOwner::Hub);
|
||||||
|
assert_eq!(firmware.os.lifecycle().resident_game_task(), None);
|
||||||
|
assert_eq!(firmware.os.lifecycle().resident_game(), None);
|
||||||
|
assert_eq!(firmware.os.lifecycle().task_state(stress_task), Some(TaskState::Closed));
|
||||||
|
assert_eq!(
|
||||||
|
firmware.os.lifecycle().process_state_for_task(stress_task),
|
||||||
|
Ok(ProcessState::Stopped)
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
firmware.os.sessions().vm_session_for_task(stress_task).map(|session| session.task_id),
|
||||||
|
None
|
||||||
|
);
|
||||||
|
assert!(!firmware.game_lifecycle_audio_paused());
|
||||||
|
assert!(!firmware.resume_resident_game_from_home());
|
||||||
|
|
||||||
|
let ownership = firmware.os.vm().active_render_ownership();
|
||||||
|
assert_eq!(ownership.app_mode, AppMode::Shell);
|
||||||
|
assert_eq!(ownership.app_id, 0);
|
||||||
|
assert_eq!(platform.local_hardware().frame_composer.active_scene_id(), None);
|
||||||
|
assert_eq!(
|
||||||
|
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
|
||||||
|
None
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
|
||||||
|
None
|
||||||
|
);
|
||||||
|
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_none());
|
||||||
|
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_none());
|
||||||
|
assert!(
|
||||||
|
firmware.os.recent_logs(32).iter().any(|event| {
|
||||||
|
event.level == LogLevel::Info
|
||||||
|
&& event.source == LogSource::Hub
|
||||||
|
&& event.msg == "Resident game killed from Hub: Stress Console"
|
||||||
|
}),
|
||||||
|
"Hub kill control should use the canonical manual kill log"
|
||||||
|
);
|
||||||
|
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
assert_eq!(
|
||||||
|
front_buffer_pixel(&platform, kill_sample_x, kill_sample_y),
|
||||||
|
Color::rgb(12, 14, 22).raw(),
|
||||||
|
"Hub should stop rendering the kill control after the game is gone"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn failed_game_switch_returns_home_without_restoring_previous_game() {
|
||||||
|
let root = TestGameRoot::new();
|
||||||
|
root.add_game("stress", true);
|
||||||
|
root.add_game_with_program("zzz-broken", 43, "Zzz Broken", "1.0.0", Some(vec![0, 0, 0, 0]));
|
||||||
|
|
||||||
|
let (mut firmware, mut platform) = hub_home_firmware();
|
||||||
|
firmware.hub.set_game_library(discover_games_root(&root.path));
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
let stress_click =
|
||||||
|
InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() };
|
||||||
|
firmware.tick(&stress_click, &mut platform);
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
let first_game_task = match &firmware.state {
|
||||||
|
FirmwareState::GameRunning(step) => step.task_id,
|
||||||
|
other => panic!("expected first GameRunning state, got {:?}", other),
|
||||||
|
};
|
||||||
|
|
||||||
|
firmware.request_home_from_host();
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
let broken_click =
|
||||||
|
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
|
||||||
|
firmware.tick(&broken_click, &mut platform);
|
||||||
|
|
||||||
|
assert_eq!(firmware.os.lifecycle().task_state(first_game_task), Some(TaskState::Closed));
|
||||||
|
assert_eq!(
|
||||||
|
firmware
|
||||||
|
.os
|
||||||
|
.sessions()
|
||||||
|
.vm_session_for_task(first_game_task)
|
||||||
|
.map(|session| session.task_id),
|
||||||
|
None
|
||||||
|
);
|
||||||
|
let partial_task = firmware
|
||||||
|
.os
|
||||||
|
.lifecycle()
|
||||||
|
.resident_game_task()
|
||||||
|
.expect("failed target should be resident until recovery tick");
|
||||||
|
assert_ne!(partial_task, first_game_task);
|
||||||
|
|
||||||
|
firmware.tick(&InputSignals::default(), &mut platform);
|
||||||
|
|
||||||
|
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
|
||||||
|
assert_eq!(firmware.os.lifecycle().resident_game_task(), None);
|
||||||
|
assert_eq!(firmware.os.lifecycle().task_state(first_game_task), Some(TaskState::Closed));
|
||||||
|
assert_eq!(firmware.os.lifecycle().task_state(partial_task), Some(TaskState::Closed));
|
||||||
|
assert_eq!(
|
||||||
|
firmware.os.lifecycle().process_state_for_task(partial_task),
|
||||||
|
Ok(ProcessState::Stopped)
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
firmware.os.sessions().vm_session_for_task(partial_task).map(|session| session.task_id),
|
||||||
|
None
|
||||||
|
);
|
||||||
|
assert!(
|
||||||
|
firmware
|
||||||
|
.os
|
||||||
|
.recent_logs(16)
|
||||||
|
.iter()
|
||||||
|
.any(|event| event.msg.contains("Failed to switch to game Zzz Broken app_id 43"))
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn invalid_games_root_candidate_is_omitted_from_home_launch_boundary() {
|
fn invalid_games_root_candidate_is_omitted_from_home_launch_boundary() {
|
||||||
let root = TestGameRoot::new();
|
let root = TestGameRoot::new();
|
||||||
@@ -989,6 +1441,8 @@ mod tests {
|
|||||||
};
|
};
|
||||||
let tick_index_before_home = firmware.os.vm().tick_index();
|
let tick_index_before_home = firmware.os.vm().tick_index();
|
||||||
let render_ownership_before_home = firmware.os.vm().active_render_ownership();
|
let render_ownership_before_home = firmware.os.vm().active_render_ownership();
|
||||||
|
assert_eq!(render_ownership_before_home.app_mode, AppMode::Game);
|
||||||
|
assert_eq!(render_ownership_before_home.app_id, 9);
|
||||||
|
|
||||||
firmware.request_home_from_host();
|
firmware.request_home_from_host();
|
||||||
|
|
||||||
@@ -1020,7 +1474,6 @@ mod tests {
|
|||||||
let render_ownership_after_home = firmware.os.vm().active_render_ownership();
|
let render_ownership_after_home = firmware.os.vm().active_render_ownership();
|
||||||
assert_eq!(render_ownership_after_home.app_mode, AppMode::Shell);
|
assert_eq!(render_ownership_after_home.app_mode, AppMode::Shell);
|
||||||
assert_eq!(render_ownership_after_home.app_id, 0);
|
assert_eq!(render_ownership_after_home.app_id, 0);
|
||||||
assert!(render_ownership_after_home.epoch > render_ownership_before_home.epoch);
|
|
||||||
assert!(firmware.os.lifecycle().pending_game_lifecycle_events().is_empty());
|
assert!(firmware.os.lifecycle().pending_game_lifecycle_events().is_empty());
|
||||||
assert_eq!(
|
assert_eq!(
|
||||||
firmware.os.vm().delivered_game_lifecycle_events().last().map(|event| event.kind),
|
firmware.os.vm().delivered_game_lifecycle_events().last().map(|event| event.kind),
|
||||||
@@ -1049,6 +1502,8 @@ mod tests {
|
|||||||
firmware.request_home_from_host();
|
firmware.request_home_from_host();
|
||||||
firmware.tick(&signals, &mut platform);
|
firmware.tick(&signals, &mut platform);
|
||||||
let hub_ownership = firmware.os.vm().active_render_ownership();
|
let hub_ownership = firmware.os.vm().active_render_ownership();
|
||||||
|
assert_eq!(hub_ownership.app_mode, AppMode::Shell);
|
||||||
|
assert_eq!(hub_ownership.app_id, 0);
|
||||||
|
|
||||||
assert!(firmware.resume_resident_game_from_home());
|
assert!(firmware.resume_resident_game_from_home());
|
||||||
assert!(matches!(firmware.state, FirmwareState::GameRunning(_)));
|
assert!(matches!(firmware.state, FirmwareState::GameRunning(_)));
|
||||||
@@ -1061,7 +1516,6 @@ mod tests {
|
|||||||
let game_ownership = firmware.os.vm().active_render_ownership();
|
let game_ownership = firmware.os.vm().active_render_ownership();
|
||||||
assert_eq!(game_ownership.app_mode, AppMode::Game);
|
assert_eq!(game_ownership.app_mode, AppMode::Game);
|
||||||
assert_eq!(game_ownership.app_id, 9);
|
assert_eq!(game_ownership.app_id, 9);
|
||||||
assert!(game_ownership.epoch > hub_ownership.epoch);
|
|
||||||
|
|
||||||
let held_signals =
|
let held_signals =
|
||||||
InputSignals { up_signal: true, f_signal: true, x_pos: 72, y_pos: 90, ..signals };
|
InputSignals { up_signal: true, f_signal: true, x_pos: 72, y_pos: 90, ..signals };
|
||||||
|
|||||||
@@ -2,6 +2,7 @@ use crate::firmware::firmware_state::{
|
|||||||
AppCrashesStep, FirmwareState, LoadCartridgeStep, ShellRunningStep,
|
AppCrashesStep, FirmwareState, LoadCartridgeStep, ShellRunningStep,
|
||||||
};
|
};
|
||||||
use crate::firmware::prometeu_context::PrometeuContext;
|
use crate::firmware::prometeu_context::PrometeuContext;
|
||||||
|
use crate::firmware::resident_game_termination;
|
||||||
use prometeu_hal::app_mode::AppMode;
|
use prometeu_hal::app_mode::AppMode;
|
||||||
use prometeu_hal::cartridge_loader::CartridgeLoader;
|
use prometeu_hal::cartridge_loader::CartridgeLoader;
|
||||||
use prometeu_hal::log::{LogLevel, LogSource};
|
use prometeu_hal::log::{LogLevel, LogSource};
|
||||||
@@ -69,7 +70,11 @@ impl HubHomeStep {
|
|||||||
return Some(FirmwareState::ResumeResidentGame);
|
return Some(FirmwareState::ResumeResidentGame);
|
||||||
}
|
}
|
||||||
|
|
||||||
if let Err(error) = ctx.os.lifecycle().terminate_resident_game() {
|
if let Err(error) = resident_game_termination::terminate_resident_game(
|
||||||
|
ctx.os,
|
||||||
|
ctx.platform,
|
||||||
|
false,
|
||||||
|
) {
|
||||||
ctx.os.log(
|
ctx.os.log(
|
||||||
LogLevel::Error,
|
LogLevel::Error,
|
||||||
LogSource::Hub,
|
LogSource::Hub,
|
||||||
@@ -83,9 +88,9 @@ impl HubHomeStep {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
return Some(FirmwareState::LoadCartridge(LoadCartridgeStep::new(
|
return Some(FirmwareState::LoadCartridge(
|
||||||
cartridge,
|
LoadCartridgeStep::new_game_switch(cartridge),
|
||||||
)));
|
));
|
||||||
}
|
}
|
||||||
Err(error) => {
|
Err(error) => {
|
||||||
ctx.os.log(
|
ctx.os.log(
|
||||||
@@ -101,6 +106,18 @@ impl HubHomeStep {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
Some(SystemProfileAction::KillResidentGame) => {
|
||||||
|
if let Err(error) =
|
||||||
|
resident_game_termination::terminate_resident_game(ctx.os, ctx.platform, true)
|
||||||
|
{
|
||||||
|
ctx.os.log(
|
||||||
|
LogLevel::Error,
|
||||||
|
LogSource::Hub,
|
||||||
|
0,
|
||||||
|
format!("Failed to kill resident game from Hub: {error:?}"),
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
Some(SystemProfileAction::CloseShell) | None => {}
|
Some(SystemProfileAction::CloseShell) | None => {}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -1,7 +1,8 @@
|
|||||||
use crate::firmware::firmware_state::{
|
use crate::firmware::firmware_state::{
|
||||||
AppCrashesStep, FirmwareState, GameRunningStep, ShellRunningStep,
|
AppCrashesStep, FirmwareState, GameRunningStep, HubHomeStep, ShellRunningStep,
|
||||||
};
|
};
|
||||||
use crate::firmware::prometeu_context::PrometeuContext;
|
use crate::firmware::prometeu_context::PrometeuContext;
|
||||||
|
use crate::firmware::resident_game_termination;
|
||||||
use prometeu_hal::app_mode::AppMode;
|
use prometeu_hal::app_mode::AppMode;
|
||||||
use prometeu_hal::cartridge::Cartridge;
|
use prometeu_hal::cartridge::Cartridge;
|
||||||
use prometeu_hal::color::Color;
|
use prometeu_hal::color::Color;
|
||||||
@@ -16,11 +17,28 @@ pub struct LoadCartridgeStep {
|
|||||||
init_error: Option<CrashReport>,
|
init_error: Option<CrashReport>,
|
||||||
loaded_task_id: Option<prometeu_system::task::TaskId>,
|
loaded_task_id: Option<prometeu_system::task::TaskId>,
|
||||||
loaded_app_mode: Option<AppMode>,
|
loaded_app_mode: Option<AppMode>,
|
||||||
|
failure_recovery: LoadCartridgeFailureRecovery,
|
||||||
|
}
|
||||||
|
|
||||||
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||||
|
enum LoadCartridgeFailureRecovery {
|
||||||
|
AppCrash,
|
||||||
|
ReturnToHub,
|
||||||
}
|
}
|
||||||
|
|
||||||
impl LoadCartridgeStep {
|
impl LoadCartridgeStep {
|
||||||
pub fn new(cartridge: Cartridge) -> Self {
|
pub fn new(cartridge: Cartridge) -> Self {
|
||||||
Self { cartridge, init_error: None, loaded_task_id: None, loaded_app_mode: None }
|
Self {
|
||||||
|
cartridge,
|
||||||
|
init_error: None,
|
||||||
|
loaded_task_id: None,
|
||||||
|
loaded_app_mode: None,
|
||||||
|
failure_recovery: LoadCartridgeFailureRecovery::AppCrash,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
pub fn new_game_switch(cartridge: Cartridge) -> Self {
|
||||||
|
Self { failure_recovery: LoadCartridgeFailureRecovery::ReturnToHub, ..Self::new(cartridge) }
|
||||||
}
|
}
|
||||||
|
|
||||||
pub fn on_enter(&mut self, ctx: &mut PrometeuContext) {
|
pub fn on_enter(&mut self, ctx: &mut PrometeuContext) {
|
||||||
@@ -31,6 +49,8 @@ impl LoadCartridgeStep {
|
|||||||
format!("Loading cartridge: {}", self.cartridge.title),
|
format!("Loading cartridge: {}", self.cartridge.title),
|
||||||
);
|
);
|
||||||
|
|
||||||
|
ctx.platform.game2d_frame_composer().unbind_scene();
|
||||||
|
|
||||||
// Initialize Asset Manager
|
// Initialize Asset Manager
|
||||||
ctx.platform.assets_mut().initialize_for_cartridge(
|
ctx.platform.assets_mut().initialize_for_cartridge(
|
||||||
self.cartridge.asset_table.clone(),
|
self.cartridge.asset_table.clone(),
|
||||||
@@ -51,6 +71,38 @@ impl LoadCartridgeStep {
|
|||||||
|
|
||||||
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
|
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
|
||||||
if let Some(report) = self.init_error.take() {
|
if let Some(report) = self.init_error.take() {
|
||||||
|
if self.failure_recovery == LoadCartridgeFailureRecovery::ReturnToHub {
|
||||||
|
if self.cartridge.app_mode == AppMode::Game
|
||||||
|
&& let Some(task_id) = ctx.os.lifecycle().resident_game_task()
|
||||||
|
{
|
||||||
|
let is_partial_target = ctx
|
||||||
|
.os
|
||||||
|
.sessions()
|
||||||
|
.vm_session_for_task(task_id)
|
||||||
|
.map(|session| session.app_id == self.cartridge.app_id)
|
||||||
|
.unwrap_or(false);
|
||||||
|
|
||||||
|
if is_partial_target {
|
||||||
|
let _ = resident_game_termination::terminate_resident_game(
|
||||||
|
ctx.os,
|
||||||
|
ctx.platform,
|
||||||
|
false,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
ctx.os.log(
|
||||||
|
LogLevel::Error,
|
||||||
|
LogSource::Hub,
|
||||||
|
0,
|
||||||
|
format!(
|
||||||
|
"Failed to switch to game {} app_id {}; returning to Home: {:?}",
|
||||||
|
self.cartridge.title, self.cartridge.app_id, report
|
||||||
|
),
|
||||||
|
);
|
||||||
|
return Some(FirmwareState::HubHome(HubHomeStep));
|
||||||
|
}
|
||||||
|
|
||||||
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
|
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -12,6 +12,7 @@ pub(crate) mod firmware_step_reset;
|
|||||||
pub(crate) mod firmware_step_shell_running;
|
pub(crate) mod firmware_step_shell_running;
|
||||||
pub(crate) mod firmware_step_splash_screen;
|
pub(crate) mod firmware_step_splash_screen;
|
||||||
mod prometeu_context;
|
mod prometeu_context;
|
||||||
|
pub(crate) mod resident_game_termination;
|
||||||
|
|
||||||
pub use boot_target::BootTarget;
|
pub use boot_target::BootTarget;
|
||||||
pub use firmware::Firmware;
|
pub use firmware::Firmware;
|
||||||
|
|||||||
@@ -0,0 +1,42 @@
|
|||||||
|
use prometeu_hal::RuntimePlatform;
|
||||||
|
use prometeu_hal::app_mode::AppMode;
|
||||||
|
use prometeu_hal::log::LogSource;
|
||||||
|
use prometeu_system::task::TaskId;
|
||||||
|
use prometeu_system::{LifecycleError, SystemOS};
|
||||||
|
|
||||||
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||||
|
pub(crate) enum ResidentGameTerminationOutcome {
|
||||||
|
NoResidentGame,
|
||||||
|
Terminated { task_id: TaskId, title: String },
|
||||||
|
}
|
||||||
|
|
||||||
|
pub(crate) fn terminate_resident_game(
|
||||||
|
os: &mut SystemOS,
|
||||||
|
platform: &mut dyn RuntimePlatform,
|
||||||
|
log_manual_hub_kill: bool,
|
||||||
|
) -> Result<ResidentGameTerminationOutcome, LifecycleError> {
|
||||||
|
let Some(task_id) = os.lifecycle().resident_game_task() else {
|
||||||
|
return Ok(ResidentGameTerminationOutcome::NoResidentGame);
|
||||||
|
};
|
||||||
|
|
||||||
|
let title = os
|
||||||
|
.sessions()
|
||||||
|
.vm_session_for_task(task_id)
|
||||||
|
.map(|session| session.title.clone())
|
||||||
|
.unwrap_or_else(|| "<unknown>".to_string());
|
||||||
|
|
||||||
|
let terminated = os.lifecycle().terminate_resident_game()?;
|
||||||
|
let Some(task_id) = terminated else {
|
||||||
|
return Ok(ResidentGameTerminationOutcome::NoResidentGame);
|
||||||
|
};
|
||||||
|
|
||||||
|
os.vm().transition_render_owner(AppMode::Shell, 0);
|
||||||
|
platform.game2d_frame_composer().unbind_scene();
|
||||||
|
platform.assets_mut().shutdown();
|
||||||
|
|
||||||
|
if log_manual_hub_kill {
|
||||||
|
os.info(LogSource::Hub, format!("Resident game killed from Hub: {title}"));
|
||||||
|
}
|
||||||
|
|
||||||
|
Ok(ResidentGameTerminationOutcome::Terminated { task_id, title })
|
||||||
|
}
|
||||||
@@ -203,7 +203,7 @@ mod tests {
|
|||||||
use super::*;
|
use super::*;
|
||||||
use crate::asset::{AssetCodec, AssetEntry, BankType, PreloadEntry};
|
use crate::asset::{AssetCodec, AssetEntry, BankType, PreloadEntry};
|
||||||
use crate::cartridge::{ASSETS_PA_MAGIC, ASSETS_PA_SCHEMA_VERSION, AssetsPackPrelude};
|
use crate::cartridge::{ASSETS_PA_MAGIC, ASSETS_PA_SCHEMA_VERSION, AssetsPackPrelude};
|
||||||
use crate::glyph_bank::GLYPH_BANK_PALETTE_COUNT_V1;
|
use crate::glyph_bank::GLYPH_BANK_MAX_PALETTE_COUNT_V1;
|
||||||
use serde_json::json;
|
use serde_json::json;
|
||||||
use std::path::{Path, PathBuf};
|
use std::path::{Path, PathBuf};
|
||||||
use std::sync::atomic::{AtomicU64, Ordering};
|
use std::sync::atomic::{AtomicU64, Ordering};
|
||||||
@@ -369,14 +369,14 @@ mod tests {
|
|||||||
bank_type: BankType::GLYPH,
|
bank_type: BankType::GLYPH,
|
||||||
offset,
|
offset,
|
||||||
size,
|
size,
|
||||||
decoded_size: 16 * 16 + (GLYPH_BANK_PALETTE_COUNT_V1 as u64 * 16 * 4),
|
decoded_size: 16 * 16 + (GLYPH_BANK_MAX_PALETTE_COUNT_V1 as u64 * 16 * 4),
|
||||||
codec: AssetCodec::None,
|
codec: AssetCodec::None,
|
||||||
metadata: json!({
|
metadata: json!({
|
||||||
"tile_size": 16,
|
"tile_size": 16,
|
||||||
"width": 16,
|
"width": 16,
|
||||||
"height": 16,
|
"height": 16,
|
||||||
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
|
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||||
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
|
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
|
||||||
}),
|
}),
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -452,14 +452,14 @@ mod tests {
|
|||||||
bank_type: BankType::GLYPH,
|
bank_type: BankType::GLYPH,
|
||||||
offset: 4,
|
offset: 4,
|
||||||
size: 4,
|
size: 4,
|
||||||
decoded_size: 16 * 16 + (GLYPH_BANK_PALETTE_COUNT_V1 as u64 * 16 * 4),
|
decoded_size: 16 * 16 + (GLYPH_BANK_MAX_PALETTE_COUNT_V1 as u64 * 16 * 4),
|
||||||
codec: AssetCodec::None,
|
codec: AssetCodec::None,
|
||||||
metadata: json!({
|
metadata: json!({
|
||||||
"tile_size": 16,
|
"tile_size": 16,
|
||||||
"width": 16,
|
"width": 16,
|
||||||
"height": 16,
|
"height": 16,
|
||||||
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
|
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||||
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
|
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
|
||||||
}),
|
}),
|
||||||
},
|
},
|
||||||
];
|
];
|
||||||
@@ -519,8 +519,8 @@ mod tests {
|
|||||||
"tile_size": 16,
|
"tile_size": 16,
|
||||||
"width": 16,
|
"width": 16,
|
||||||
"height": 16,
|
"height": 16,
|
||||||
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
|
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||||
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
|
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
|
||||||
}
|
}
|
||||||
}],
|
}],
|
||||||
"preload": []
|
"preload": []
|
||||||
@@ -561,8 +561,8 @@ mod tests {
|
|||||||
"tile_size": 16,
|
"tile_size": 16,
|
||||||
"width": 16,
|
"width": 16,
|
||||||
"height": 16,
|
"height": 16,
|
||||||
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
|
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||||
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
|
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
|
||||||
}
|
}
|
||||||
}],
|
}],
|
||||||
"preload": []
|
"preload": []
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
use crate::color::Color;
|
use crate::color::Color;
|
||||||
use serde::{Deserialize, Serialize};
|
use serde::{Deserialize, Serialize};
|
||||||
|
|
||||||
pub const GLYPH_BANK_PALETTE_COUNT_V1: usize = 64;
|
pub const GLYPH_BANK_MAX_PALETTE_COUNT_V1: usize = 64;
|
||||||
pub const GLYPH_BANK_COLORS_PER_PALETTE: usize = 16;
|
pub const GLYPH_BANK_COLORS_PER_PALETTE: usize = 16;
|
||||||
|
|
||||||
/// Standard sizes for square tiles.
|
/// Standard sizes for square tiles.
|
||||||
@@ -35,22 +35,59 @@ pub struct GlyphBank {
|
|||||||
/// Palette indices are ordinary indices; transparency is resolved through
|
/// Palette indices are ordinary indices; transparency is resolved through
|
||||||
/// the RGBA alpha channel of the palette entry.
|
/// the RGBA alpha channel of the palette entry.
|
||||||
pub pixel_indices: Vec<u8>,
|
pub pixel_indices: Vec<u8>,
|
||||||
/// Runtime-facing v1 palette table: 64 palettes of 16 RGBA8888 colors each.
|
/// Runtime-facing v1 palette table.
|
||||||
pub palettes: [[Color; GLYPH_BANK_COLORS_PER_PALETTE]; GLYPH_BANK_PALETTE_COUNT_V1],
|
///
|
||||||
|
/// Palette identity is the direct index in this vector. A resident glyph
|
||||||
|
/// bank carries exactly the palettes materialized from its payload.
|
||||||
|
pub palettes: Vec<[Color; GLYPH_BANK_COLORS_PER_PALETTE]>,
|
||||||
}
|
}
|
||||||
|
|
||||||
impl GlyphBank {
|
impl GlyphBank {
|
||||||
/// Creates an empty glyph bank with the specified dimensions.
|
/// Creates an empty glyph bank with one palette.
|
||||||
pub fn new(tile_size: TileSize, width: usize, height: usize) -> Self {
|
pub fn new(tile_size: TileSize, width: usize, height: usize) -> Self {
|
||||||
|
Self::with_palette_count(tile_size, width, height, 1)
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Creates an empty glyph bank with the specified resident palette count.
|
||||||
|
pub fn with_palette_count(
|
||||||
|
tile_size: TileSize,
|
||||||
|
width: usize,
|
||||||
|
height: usize,
|
||||||
|
palette_count: usize,
|
||||||
|
) -> Self {
|
||||||
|
assert!(
|
||||||
|
(1..=GLYPH_BANK_MAX_PALETTE_COUNT_V1).contains(&palette_count),
|
||||||
|
"glyph bank palette_count must be in 1..={}",
|
||||||
|
GLYPH_BANK_MAX_PALETTE_COUNT_V1
|
||||||
|
);
|
||||||
|
|
||||||
Self {
|
Self {
|
||||||
tile_size,
|
tile_size,
|
||||||
width,
|
width,
|
||||||
height,
|
height,
|
||||||
pixel_indices: vec![0; width * height],
|
pixel_indices: vec![0; width * height],
|
||||||
palettes: [[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; GLYPH_BANK_PALETTE_COUNT_V1],
|
palettes: vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count],
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Returns the number of resident palettes.
|
||||||
|
pub fn palette_count(&self) -> usize {
|
||||||
|
self.palettes.len()
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Returns true when the palette id is valid for this resident bank.
|
||||||
|
pub fn contains_palette(&self, palette_id: u8) -> bool {
|
||||||
|
(palette_id as usize) < self.palette_count()
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Returns a mutable palette slot when the palette exists.
|
||||||
|
pub fn palette_mut(
|
||||||
|
&mut self,
|
||||||
|
palette_id: u8,
|
||||||
|
) -> Option<&mut [Color; GLYPH_BANK_COLORS_PER_PALETTE]> {
|
||||||
|
self.palettes.get_mut(palette_id as usize)
|
||||||
|
}
|
||||||
|
|
||||||
/// Resolves a global tile ID and local pixel coordinates to a palette index.
|
/// Resolves a global tile ID and local pixel coordinates to a palette index.
|
||||||
/// tile_id: the tile index in the bank
|
/// tile_id: the tile index in the bank
|
||||||
/// local_x, local_y: the pixel position inside the tile (0 to tile_size-1)
|
/// local_x, local_y: the pixel position inside the tile (0 to tile_size-1)
|
||||||
@@ -71,11 +108,48 @@ impl GlyphBank {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/// Maps a 4-bit index to a real RGBA8888 Color using the specified palette.
|
/// Maps a 4-bit index to a real RGBA8888 Color using the specified palette.
|
||||||
pub fn resolve_color(&self, palette_id: u8, pixel_index: u8) -> Color {
|
pub fn resolve_color(&self, palette_id: u8, pixel_index: u8) -> Option<Color> {
|
||||||
self.palettes
|
self.palettes
|
||||||
.get(palette_id as usize)
|
.get(palette_id as usize)
|
||||||
.and_then(|palette| palette.get(pixel_index as usize))
|
.and_then(|palette| palette.get(pixel_index as usize))
|
||||||
.copied()
|
.copied()
|
||||||
.unwrap_or(Color::TRANSPARENT)
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(test)]
|
||||||
|
mod tests {
|
||||||
|
use super::*;
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn new_glyph_bank_uses_single_resident_palette() {
|
||||||
|
let bank = GlyphBank::new(TileSize::Size8, 8, 8);
|
||||||
|
|
||||||
|
assert_eq!(bank.palette_count(), 1);
|
||||||
|
assert!(bank.contains_palette(0));
|
||||||
|
assert!(!bank.contains_palette(1));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn glyph_bank_can_materialize_v1_max_palette_count() {
|
||||||
|
let bank =
|
||||||
|
GlyphBank::with_palette_count(TileSize::Size8, 8, 8, GLYPH_BANK_MAX_PALETTE_COUNT_V1);
|
||||||
|
|
||||||
|
assert_eq!(bank.palette_count(), GLYPH_BANK_MAX_PALETTE_COUNT_V1);
|
||||||
|
assert!(bank.contains_palette((GLYPH_BANK_MAX_PALETTE_COUNT_V1 - 1) as u8));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn invalid_palette_lookup_is_distinct_from_transparent_color() {
|
||||||
|
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
|
||||||
|
bank.palette_mut(0).unwrap()[1] = Color::TRANSPARENT;
|
||||||
|
|
||||||
|
assert_eq!(bank.resolve_color(0, 1), Some(Color::TRANSPARENT));
|
||||||
|
assert_eq!(bank.resolve_color(1, 1), None);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
#[should_panic(expected = "glyph bank palette_count must be in 1..=64")]
|
||||||
|
fn glyph_bank_rejects_zero_resident_palettes() {
|
||||||
|
let _ = GlyphBank::with_palette_count(TileSize::Size8, 8, 8, 0);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -8,7 +8,10 @@ pub use os::{
|
|||||||
DEFAULT_GAME_PAUSE_BUDGET_TICKS, GameLifecycleEvent, GameLifecycleEventKind, LifecycleError,
|
DEFAULT_GAME_PAUSE_BUDGET_TICKS, GameLifecycleEvent, GameLifecycleEventKind, LifecycleError,
|
||||||
LifecycleOperation, SessionError, SystemOS,
|
LifecycleOperation, SessionError, SystemOS,
|
||||||
};
|
};
|
||||||
pub use programs::{NativeShellApp, PrometeuHub, SystemProfileAction, SystemProfileUpdate};
|
pub use programs::{
|
||||||
|
HUB_SUSPENDED_GAME_KILL_CONTROL, NativeShellApp, PrometeuHub, SystemProfileAction,
|
||||||
|
SystemProfileUpdate,
|
||||||
|
};
|
||||||
pub use prometeu_hal::{RenderWorkerBackend, RenderWorkerFrameSink};
|
pub use prometeu_hal::{RenderWorkerBackend, RenderWorkerFrameSink};
|
||||||
pub use services::async_work::{
|
pub use services::async_work::{
|
||||||
AsyncWorkActiveJob, AsyncWorkCancelToken, AsyncWorkJobContext, AsyncWorkJobId,
|
AsyncWorkActiveJob, AsyncWorkCancelToken, AsyncWorkJobContext, AsyncWorkJobId,
|
||||||
|
|||||||
@@ -250,6 +250,12 @@ impl<'a> VmFacade<'a> {
|
|||||||
}
|
}
|
||||||
|
|
||||||
pub fn active_render_ownership(&self) -> RenderOwnership {
|
pub fn active_render_ownership(&self) -> RenderOwnership {
|
||||||
|
if let Some(task_id) = self.foreground_session_task_id()
|
||||||
|
&& let Some(session) = self.os.vm_sessions.for_task(task_id)
|
||||||
|
{
|
||||||
|
return session.runtime.render_manager.active_ownership();
|
||||||
|
}
|
||||||
|
|
||||||
self.os.vm_runtime.render_manager.active_ownership()
|
self.os.vm_runtime.render_manager.active_ownership()
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -317,4 +323,8 @@ impl<'a> VmFacade<'a> {
|
|||||||
.foreground_task()
|
.foreground_task()
|
||||||
.or_else(|| self.os.foreground_stack.resident_game_task())
|
.or_else(|| self.os.foreground_stack.resident_game_task())
|
||||||
}
|
}
|
||||||
|
|
||||||
|
fn foreground_session_task_id(&self) -> Option<TaskId> {
|
||||||
|
self.os.task_manager.foreground_task()
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,3 +1,6 @@
|
|||||||
mod prometeu_hub;
|
mod prometeu_hub;
|
||||||
|
|
||||||
pub use prometeu_hub::{NativeShellApp, PrometeuHub, SystemProfileAction, SystemProfileUpdate};
|
pub use prometeu_hub::{
|
||||||
|
HUB_SUSPENDED_GAME_KILL_CONTROL, NativeShellApp, PrometeuHub, SystemProfileAction,
|
||||||
|
SystemProfileUpdate,
|
||||||
|
};
|
||||||
|
|||||||
@@ -1,4 +1,7 @@
|
|||||||
#[allow(clippy::module_inception)]
|
#[allow(clippy::module_inception)]
|
||||||
mod prometeu_hub;
|
mod prometeu_hub;
|
||||||
|
|
||||||
pub use prometeu_hub::{NativeShellApp, PrometeuHub, SystemProfileAction, SystemProfileUpdate};
|
pub use prometeu_hub::{
|
||||||
|
HUB_SUSPENDED_GAME_KILL_CONTROL, NativeShellApp, PrometeuHub, SystemProfileAction,
|
||||||
|
SystemProfileUpdate,
|
||||||
|
};
|
||||||
|
|||||||
@@ -1,5 +1,6 @@
|
|||||||
use crate::task::TaskId;
|
use crate::task::TaskId;
|
||||||
use crate::{CrashReport, GameLibrary, GameSwitchTarget, SystemOS};
|
use crate::{CrashReport, GameLibrary, GameSwitchTarget, SystemOS};
|
||||||
|
use prometeu_hal::app_mode::AppMode;
|
||||||
use prometeu_hal::color::Color;
|
use prometeu_hal::color::Color;
|
||||||
use prometeu_hal::primitives::Rect;
|
use prometeu_hal::primitives::Rect;
|
||||||
use prometeu_hal::{
|
use prometeu_hal::{
|
||||||
@@ -19,6 +20,7 @@ const GAME_ROW_W: i32 = 336;
|
|||||||
const GAME_ROW_H: i32 = 22;
|
const GAME_ROW_H: i32 = 22;
|
||||||
const GAME_ROW_GAP: i32 = 6;
|
const GAME_ROW_GAP: i32 = 6;
|
||||||
const MAX_HOME_GAME_ROWS: usize = 3;
|
const MAX_HOME_GAME_ROWS: usize = 3;
|
||||||
|
pub const HUB_SUSPENDED_GAME_KILL_CONTROL: Rect = Rect { x: 288, y: 230, w: 168, h: 24 };
|
||||||
#[cfg(test)]
|
#[cfg(test)]
|
||||||
const SHELL_FRAME: Rect = Rect { x: 40, y: 20, w: 400, h: 220 };
|
const SHELL_FRAME: Rect = Rect { x: 40, y: 20, w: 400, h: 220 };
|
||||||
|
|
||||||
@@ -31,6 +33,8 @@ const COLOR_TEXT: Color = Color::rgb(230, 236, 224);
|
|||||||
const COLOR_MUTED: Color = Color::rgb(91, 112, 128);
|
const COLOR_MUTED: Color = Color::rgb(91, 112, 128);
|
||||||
const COLOR_BUTTON: Color = Color::rgb(45, 59, 82);
|
const COLOR_BUTTON: Color = Color::rgb(45, 59, 82);
|
||||||
const COLOR_BUTTON_ACTIVE: Color = Color::rgb(72, 91, 122);
|
const COLOR_BUTTON_ACTIVE: Color = Color::rgb(72, 91, 122);
|
||||||
|
const COLOR_KILL: Color = Color::rgb(164, 32, 40);
|
||||||
|
const COLOR_KILL_ACTIVE: Color = Color::rgb(206, 46, 54);
|
||||||
|
|
||||||
/// PrometeuHub: Launcher and system UI environment.
|
/// PrometeuHub: Launcher and system UI environment.
|
||||||
pub struct PrometeuHub {
|
pub struct PrometeuHub {
|
||||||
@@ -83,6 +87,7 @@ impl NativeShellApp {
|
|||||||
pub enum SystemProfileAction {
|
pub enum SystemProfileAction {
|
||||||
LaunchNativeShell(NativeShellApp),
|
LaunchNativeShell(NativeShellApp),
|
||||||
LaunchGame { target: GameSwitchTarget },
|
LaunchGame { target: GameSwitchTarget },
|
||||||
|
KillResidentGame,
|
||||||
CloseShell,
|
CloseShell,
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -131,12 +136,14 @@ impl PrometeuHub {
|
|||||||
}
|
}
|
||||||
|
|
||||||
let input = platform.input();
|
let input = platform.input();
|
||||||
|
let suspended_game = if in_shell { None } else { resident_game_indicator(os) };
|
||||||
if let Some(action) = action_for_click(
|
if let Some(action) = action_for_click(
|
||||||
in_shell,
|
in_shell,
|
||||||
input.touch().x(),
|
input.touch().x(),
|
||||||
input.touch().y(),
|
input.touch().y(),
|
||||||
input.touch().f().pressed,
|
input.touch().f().pressed,
|
||||||
self.game_library.entries(),
|
self.game_library.entries(),
|
||||||
|
suspended_game.as_ref(),
|
||||||
) {
|
) {
|
||||||
return Some(action);
|
return Some(action);
|
||||||
}
|
}
|
||||||
@@ -149,7 +156,13 @@ impl PrometeuHub {
|
|||||||
let pointer_y = platform.input().touch().y();
|
let pointer_y = platform.input().touch().y();
|
||||||
|
|
||||||
let packet = if os.windows().window_count() == 0 {
|
let packet = if os.windows().window_count() == 0 {
|
||||||
render_home_packet(pointer_x, pointer_y, self.game_library.entries())
|
let suspended_game = resident_game_indicator(os);
|
||||||
|
render_home_packet(
|
||||||
|
pointer_x,
|
||||||
|
pointer_y,
|
||||||
|
self.game_library.entries(),
|
||||||
|
suspended_game.as_ref(),
|
||||||
|
)
|
||||||
} else {
|
} else {
|
||||||
let mut commands = Vec::new();
|
let mut commands = Vec::new();
|
||||||
for window in os.windows().windows() {
|
for window in os.windows().windows() {
|
||||||
@@ -232,6 +245,7 @@ fn action_for_click(
|
|||||||
y: i32,
|
y: i32,
|
||||||
pressed: bool,
|
pressed: bool,
|
||||||
game_entries: &[crate::GameLibraryEntry],
|
game_entries: &[crate::GameLibraryEntry],
|
||||||
|
suspended_game: Option<&SuspendedGameIndicator>,
|
||||||
) -> Option<SystemProfileAction> {
|
) -> Option<SystemProfileAction> {
|
||||||
if !pressed {
|
if !pressed {
|
||||||
return None;
|
return None;
|
||||||
@@ -241,6 +255,10 @@ fn action_for_click(
|
|||||||
return rect_contains(CLOSE_BUTTON, x, y).then_some(SystemProfileAction::CloseShell);
|
return rect_contains(CLOSE_BUTTON, x, y).then_some(SystemProfileAction::CloseShell);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
if suspended_game.is_some() && rect_contains(HUB_SUSPENDED_GAME_KILL_CONTROL, x, y) {
|
||||||
|
return Some(SystemProfileAction::KillResidentGame);
|
||||||
|
}
|
||||||
|
|
||||||
if let Some(entry) = game_entries
|
if let Some(entry) = game_entries
|
||||||
.iter()
|
.iter()
|
||||||
.take(MAX_HOME_GAME_ROWS)
|
.take(MAX_HOME_GAME_ROWS)
|
||||||
@@ -257,6 +275,23 @@ fn action_for_click(
|
|||||||
.map(|button| SystemProfileAction::LaunchNativeShell(button.app))
|
.map(|button| SystemProfileAction::LaunchNativeShell(button.app))
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||||
|
struct SuspendedGameIndicator {
|
||||||
|
title: String,
|
||||||
|
}
|
||||||
|
|
||||||
|
fn resident_game_indicator(os: &mut SystemOS) -> Option<SuspendedGameIndicator> {
|
||||||
|
let task_id = os.lifecycle().resident_game_task()?;
|
||||||
|
let sessions = os.sessions();
|
||||||
|
let session = sessions.vm_session_for_task(task_id)?;
|
||||||
|
|
||||||
|
if session.app_mode != AppMode::Game {
|
||||||
|
return None;
|
||||||
|
}
|
||||||
|
|
||||||
|
Some(SuspendedGameIndicator { title: session.title.clone() })
|
||||||
|
}
|
||||||
|
|
||||||
fn game_row_rect(index: usize) -> Rect {
|
fn game_row_rect(index: usize) -> Rect {
|
||||||
Rect {
|
Rect {
|
||||||
x: GAME_ROW_X,
|
x: GAME_ROW_X,
|
||||||
@@ -281,6 +316,7 @@ fn render_home_packet(
|
|||||||
pointer_x: i32,
|
pointer_x: i32,
|
||||||
pointer_y: i32,
|
pointer_y: i32,
|
||||||
game_entries: &[crate::GameLibraryEntry],
|
game_entries: &[crate::GameLibraryEntry],
|
||||||
|
suspended_game: Option<&SuspendedGameIndicator>,
|
||||||
) -> ShellUiFramePacket {
|
) -> ShellUiFramePacket {
|
||||||
let mut commands = Vec::new();
|
let mut commands = Vec::new();
|
||||||
commands.push(GfxUiCommand::Clear { color: COLOR_BG });
|
commands.push(GfxUiCommand::Clear { color: COLOR_BG });
|
||||||
@@ -320,6 +356,11 @@ fn render_home_packet(
|
|||||||
draw_button(&mut commands, button.rect, button.label, hovered);
|
draw_button(&mut commands, button.rect, button.label, hovered);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
if let Some(suspended_game) = suspended_game {
|
||||||
|
let hovered = rect_contains(HUB_SUSPENDED_GAME_KILL_CONTROL, pointer_x, pointer_y);
|
||||||
|
draw_suspended_game_kill_control(&mut commands, suspended_game, hovered);
|
||||||
|
}
|
||||||
|
|
||||||
ShellUiFramePacket::new(commands)
|
ShellUiFramePacket::new(commands)
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -422,6 +463,39 @@ fn draw_game_row(commands: &mut Vec<GfxUiCommand>, rect: Rect, label: &str, hove
|
|||||||
draw_buffer_text(commands, rect.x + 8, rect.y + 7, label, COLOR_TEXT);
|
draw_buffer_text(commands, rect.x + 8, rect.y + 7, label, COLOR_TEXT);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
fn draw_suspended_game_kill_control(
|
||||||
|
commands: &mut Vec<GfxUiCommand>,
|
||||||
|
suspended_game: &SuspendedGameIndicator,
|
||||||
|
hovered: bool,
|
||||||
|
) {
|
||||||
|
let fill = if hovered { COLOR_KILL_ACTIVE } else { COLOR_KILL };
|
||||||
|
let border = if hovered { COLOR_HILITE } else { COLOR_BORDER };
|
||||||
|
fill_rect(commands, HUB_SUSPENDED_GAME_KILL_CONTROL, fill);
|
||||||
|
draw_rect(commands, HUB_SUSPENDED_GAME_KILL_CONTROL, border);
|
||||||
|
draw_buffer_text(
|
||||||
|
commands,
|
||||||
|
HUB_SUSPENDED_GAME_KILL_CONTROL.x + 8,
|
||||||
|
HUB_SUSPENDED_GAME_KILL_CONTROL.y + 8,
|
||||||
|
&fit_text_to_control(&suspended_game.title, HUB_SUSPENDED_GAME_KILL_CONTROL.w - 16),
|
||||||
|
COLOR_TEXT,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
fn fit_text_to_control(text: &str, max_width: i32) -> String {
|
||||||
|
let max_chars = (max_width / 8).max(0) as usize;
|
||||||
|
if text.chars().count() <= max_chars {
|
||||||
|
return text.to_string();
|
||||||
|
}
|
||||||
|
|
||||||
|
if max_chars <= 2 {
|
||||||
|
return text.chars().take(max_chars).collect();
|
||||||
|
}
|
||||||
|
|
||||||
|
let mut fitted: String = text.chars().take(max_chars - 2).collect();
|
||||||
|
fitted.push_str("..");
|
||||||
|
fitted
|
||||||
|
}
|
||||||
|
|
||||||
fn draw_buffer_text(commands: &mut Vec<GfxUiCommand>, x: i32, y: i32, text: &str, color: Color) {
|
fn draw_buffer_text(commands: &mut Vec<GfxUiCommand>, x: i32, y: i32, text: &str, color: Color) {
|
||||||
commands.push(GfxUiCommand::DrawText { x, y, text: text.to_string(), color });
|
commands.push(GfxUiCommand::DrawText { x, y, text: text.to_string(), color });
|
||||||
}
|
}
|
||||||
@@ -462,7 +536,14 @@ mod tests {
|
|||||||
#[test]
|
#[test]
|
||||||
fn shell_a_button_click_emits_launch_action() {
|
fn shell_a_button_click_emits_launch_action() {
|
||||||
assert_eq!(
|
assert_eq!(
|
||||||
action_for_click(false, HOME_BUTTONS[0].rect.x, HOME_BUTTONS[0].rect.y, true, &[]),
|
action_for_click(
|
||||||
|
false,
|
||||||
|
HOME_BUTTONS[0].rect.x,
|
||||||
|
HOME_BUTTONS[0].rect.y,
|
||||||
|
true,
|
||||||
|
&[],
|
||||||
|
None
|
||||||
|
),
|
||||||
Some(SystemProfileAction::LaunchNativeShell(NativeShellApp::ShellA))
|
Some(SystemProfileAction::LaunchNativeShell(NativeShellApp::ShellA))
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
@@ -475,7 +556,8 @@ mod tests {
|
|||||||
SHELL_B_BUTTON.x + SHELL_B_BUTTON.w - 1,
|
SHELL_B_BUTTON.x + SHELL_B_BUTTON.w - 1,
|
||||||
SHELL_B_BUTTON.y,
|
SHELL_B_BUTTON.y,
|
||||||
true,
|
true,
|
||||||
&[]
|
&[],
|
||||||
|
None
|
||||||
),
|
),
|
||||||
Some(SystemProfileAction::LaunchNativeShell(NativeShellApp::ShellB))
|
Some(SystemProfileAction::LaunchNativeShell(NativeShellApp::ShellB))
|
||||||
);
|
);
|
||||||
@@ -489,7 +571,8 @@ mod tests {
|
|||||||
SHELL_A_BUTTON.x + SHELL_A_BUTTON.w,
|
SHELL_A_BUTTON.x + SHELL_A_BUTTON.w,
|
||||||
SHELL_A_BUTTON.y,
|
SHELL_A_BUTTON.y,
|
||||||
true,
|
true,
|
||||||
&[]
|
&[],
|
||||||
|
None
|
||||||
),
|
),
|
||||||
None
|
None
|
||||||
);
|
);
|
||||||
@@ -499,7 +582,8 @@ mod tests {
|
|||||||
SHELL_A_BUTTON.x,
|
SHELL_A_BUTTON.x,
|
||||||
SHELL_A_BUTTON.y + SHELL_A_BUTTON.h,
|
SHELL_A_BUTTON.y + SHELL_A_BUTTON.h,
|
||||||
true,
|
true,
|
||||||
&[]
|
&[],
|
||||||
|
None
|
||||||
),
|
),
|
||||||
None
|
None
|
||||||
);
|
);
|
||||||
@@ -507,7 +591,10 @@ mod tests {
|
|||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn held_pointer_does_not_emit_click_action() {
|
fn held_pointer_does_not_emit_click_action() {
|
||||||
assert_eq!(action_for_click(false, SHELL_A_BUTTON.x, SHELL_A_BUTTON.y, false, &[]), None);
|
assert_eq!(
|
||||||
|
action_for_click(false, SHELL_A_BUTTON.x, SHELL_A_BUTTON.y, false, &[], None),
|
||||||
|
None
|
||||||
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
@@ -535,8 +622,14 @@ mod tests {
|
|||||||
discovered_at: std::time::SystemTime::UNIX_EPOCH,
|
discovered_at: std::time::SystemTime::UNIX_EPOCH,
|
||||||
};
|
};
|
||||||
|
|
||||||
let action =
|
let action = action_for_click(
|
||||||
action_for_click(false, GAME_ROW_X, GAME_ROW_Y, true, std::slice::from_ref(&entry));
|
false,
|
||||||
|
GAME_ROW_X,
|
||||||
|
GAME_ROW_Y,
|
||||||
|
true,
|
||||||
|
std::slice::from_ref(&entry),
|
||||||
|
None,
|
||||||
|
);
|
||||||
|
|
||||||
assert_eq!(
|
assert_eq!(
|
||||||
action,
|
action,
|
||||||
@@ -554,10 +647,10 @@ mod tests {
|
|||||||
#[test]
|
#[test]
|
||||||
fn close_button_click_emits_close_only_in_shell() {
|
fn close_button_click_emits_close_only_in_shell() {
|
||||||
assert_eq!(
|
assert_eq!(
|
||||||
action_for_click(true, CLOSE_BUTTON.x, CLOSE_BUTTON.y, true, &[]),
|
action_for_click(true, CLOSE_BUTTON.x, CLOSE_BUTTON.y, true, &[], None),
|
||||||
Some(SystemProfileAction::CloseShell)
|
Some(SystemProfileAction::CloseShell)
|
||||||
);
|
);
|
||||||
assert_eq!(action_for_click(false, CLOSE_BUTTON.x, CLOSE_BUTTON.y, true, &[]), None);
|
assert_eq!(action_for_click(false, CLOSE_BUTTON.x, CLOSE_BUTTON.y, true, &[], None), None);
|
||||||
}
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
@@ -571,7 +664,7 @@ mod tests {
|
|||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn home_render_produces_shell_ui_packet_commands() {
|
fn home_render_produces_shell_ui_packet_commands() {
|
||||||
let packet = render_home_packet(SHELL_A_BUTTON.x, SHELL_A_BUTTON.y, &[]);
|
let packet = render_home_packet(SHELL_A_BUTTON.x, SHELL_A_BUTTON.y, &[], None);
|
||||||
|
|
||||||
assert!(matches!(packet.commands.first(), Some(GfxUiCommand::Clear { .. })));
|
assert!(matches!(packet.commands.first(), Some(GfxUiCommand::Clear { .. })));
|
||||||
assert!(packet.commands.iter().any(|command| {
|
assert!(packet.commands.iter().any(|command| {
|
||||||
@@ -579,6 +672,123 @@ mod tests {
|
|||||||
}));
|
}));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn resident_game_indicator_uses_only_resident_game_sessions() {
|
||||||
|
let mut os = SystemOS::new(None);
|
||||||
|
assert_eq!(resident_game_indicator(&mut os), None);
|
||||||
|
|
||||||
|
let shell = os.sessions().create_vm_shell_task(7, "VM Shell");
|
||||||
|
assert_eq!(resident_game_indicator(&mut os), None);
|
||||||
|
os.lifecycle().suspend_task(shell).expect("shell suspend should succeed");
|
||||||
|
assert_eq!(resident_game_indicator(&mut os), None);
|
||||||
|
|
||||||
|
let game = os.sessions().create_vm_game_task(42, "Stress Console");
|
||||||
|
os.lifecycle().suspend_task(game).expect("game suspend should succeed");
|
||||||
|
|
||||||
|
assert_eq!(
|
||||||
|
resident_game_indicator(&mut os),
|
||||||
|
Some(SuspendedGameIndicator { title: "Stress Console".to_string() })
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn home_render_shows_suspended_game_kill_control_when_game_is_resident() {
|
||||||
|
let suspended_game = SuspendedGameIndicator { title: "Stress Console".to_string() };
|
||||||
|
let packet = render_home_packet(
|
||||||
|
HUB_SUSPENDED_GAME_KILL_CONTROL.x,
|
||||||
|
HUB_SUSPENDED_GAME_KILL_CONTROL.y,
|
||||||
|
&[],
|
||||||
|
Some(&suspended_game),
|
||||||
|
);
|
||||||
|
|
||||||
|
assert!(packet.commands.iter().any(|command| {
|
||||||
|
matches!(
|
||||||
|
command,
|
||||||
|
GfxUiCommand::FillRect { rect, color }
|
||||||
|
if *rect == HUB_SUSPENDED_GAME_KILL_CONTROL && *color == COLOR_KILL_ACTIVE
|
||||||
|
)
|
||||||
|
}));
|
||||||
|
assert!(packet.commands.iter().any(|command| {
|
||||||
|
matches!(
|
||||||
|
command,
|
||||||
|
GfxUiCommand::DrawText { x, y, text, .. }
|
||||||
|
if *x == HUB_SUSPENDED_GAME_KILL_CONTROL.x + 8
|
||||||
|
&& *y == HUB_SUSPENDED_GAME_KILL_CONTROL.y + 8
|
||||||
|
&& text == "Stress Console"
|
||||||
|
)
|
||||||
|
}));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn home_render_omits_suspended_game_kill_control_without_resident_game() {
|
||||||
|
let packet = render_home_packet(
|
||||||
|
HUB_SUSPENDED_GAME_KILL_CONTROL.x,
|
||||||
|
HUB_SUSPENDED_GAME_KILL_CONTROL.y,
|
||||||
|
&[],
|
||||||
|
None,
|
||||||
|
);
|
||||||
|
|
||||||
|
assert!(!packet.commands.iter().any(|command| {
|
||||||
|
matches!(
|
||||||
|
command,
|
||||||
|
GfxUiCommand::FillRect { rect, color }
|
||||||
|
if *rect == HUB_SUSPENDED_GAME_KILL_CONTROL
|
||||||
|
&& (*color == COLOR_KILL || *color == COLOR_KILL_ACTIVE)
|
||||||
|
)
|
||||||
|
}));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn suspended_game_kill_control_click_emits_kill_action() {
|
||||||
|
let suspended_game = SuspendedGameIndicator { title: "Stress Console".to_string() };
|
||||||
|
|
||||||
|
assert_eq!(
|
||||||
|
action_for_click(
|
||||||
|
false,
|
||||||
|
HUB_SUSPENDED_GAME_KILL_CONTROL.x,
|
||||||
|
HUB_SUSPENDED_GAME_KILL_CONTROL.y,
|
||||||
|
true,
|
||||||
|
&[],
|
||||||
|
Some(&suspended_game),
|
||||||
|
),
|
||||||
|
Some(SystemProfileAction::KillResidentGame)
|
||||||
|
);
|
||||||
|
assert_eq!(
|
||||||
|
action_for_click(
|
||||||
|
false,
|
||||||
|
HUB_SUSPENDED_GAME_KILL_CONTROL.x,
|
||||||
|
HUB_SUSPENDED_GAME_KILL_CONTROL.y,
|
||||||
|
true,
|
||||||
|
&[],
|
||||||
|
None,
|
||||||
|
),
|
||||||
|
None
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn suspended_game_kill_control_truncates_long_titles() {
|
||||||
|
let long_title =
|
||||||
|
SuspendedGameIndicator { title: "Extremely Long Resident Game Title".to_string() };
|
||||||
|
let packet = render_home_packet(0, 0, &[], Some(&long_title));
|
||||||
|
let label = packet
|
||||||
|
.commands
|
||||||
|
.iter()
|
||||||
|
.find_map(|command| match command {
|
||||||
|
GfxUiCommand::DrawText { x, y, text, .. }
|
||||||
|
if *x == HUB_SUSPENDED_GAME_KILL_CONTROL.x + 8
|
||||||
|
&& *y == HUB_SUSPENDED_GAME_KILL_CONTROL.y + 8 =>
|
||||||
|
{
|
||||||
|
Some(text)
|
||||||
|
}
|
||||||
|
_ => None,
|
||||||
|
})
|
||||||
|
.expect("kill control text should render");
|
||||||
|
|
||||||
|
assert!(label.ends_with(".."));
|
||||||
|
assert!(label.chars().count() <= ((HUB_SUSPENDED_GAME_KILL_CONTROL.w - 16) / 8) as usize);
|
||||||
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn shell_close_button_sits_inside_shell_frame() {
|
fn shell_close_button_sits_inside_shell_frame() {
|
||||||
assert!(rect_contains(SHELL_FRAME, CLOSE_BUTTON.x, CLOSE_BUTTON.y));
|
assert!(rect_contains(SHELL_FRAME, CLOSE_BUTTON.x, CLOSE_BUTTON.y));
|
||||||
|
|||||||
@@ -315,4 +315,22 @@ mod tests {
|
|||||||
assert_eq!(library.diagnostics().len(), 1);
|
assert_eq!(library.diagnostics().len(), 1);
|
||||||
assert_eq!(library.diagnostics()[0].reason, GameLibraryDiagnosticReason::RootNotDirectory);
|
assert_eq!(library.diagnostics()[0].reason, GameLibraryDiagnosticReason::RootNotDirectory);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn repository_test_cartridges_include_stress_and_dummy_boy() {
|
||||||
|
let games_root =
|
||||||
|
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../..").join("test-cartridges");
|
||||||
|
|
||||||
|
let library = discover_games_root(games_root);
|
||||||
|
let entries = library.entries();
|
||||||
|
|
||||||
|
assert!(entries.iter().any(|entry| {
|
||||||
|
entry.app_id == 1
|
||||||
|
&& entry.title == "Stress Console"
|
||||||
|
&& entry.path.ends_with("stress-console")
|
||||||
|
}));
|
||||||
|
assert!(entries.iter().any(|entry| {
|
||||||
|
entry.app_id == 2 && entry.title == "Dummy Boy" && entry.path.ends_with("dummy-boy")
|
||||||
|
}));
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -15,7 +15,7 @@ use prometeu_hal::asset::{
|
|||||||
use prometeu_hal::cartridge::{AssetsPayloadSource, Cartridge};
|
use prometeu_hal::cartridge::{AssetsPayloadSource, Cartridge};
|
||||||
use prometeu_hal::color::Color;
|
use prometeu_hal::color::Color;
|
||||||
use prometeu_hal::glyph::Glyph;
|
use prometeu_hal::glyph::Glyph;
|
||||||
use prometeu_hal::glyph_bank::{GLYPH_BANK_PALETTE_COUNT_V1, GlyphBank, TileSize};
|
use prometeu_hal::glyph_bank::{GLYPH_BANK_MAX_PALETTE_COUNT_V1, GlyphBank, TileSize};
|
||||||
use prometeu_hal::scene_bank::SceneBank;
|
use prometeu_hal::scene_bank::SceneBank;
|
||||||
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
|
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
|
||||||
use prometeu_hal::syscalls::caps;
|
use prometeu_hal::syscalls::caps;
|
||||||
@@ -113,11 +113,12 @@ fn serialized_single_function_module_with_consts(
|
|||||||
}
|
}
|
||||||
|
|
||||||
fn test_glyph_payload_size(width: usize, height: usize) -> usize {
|
fn test_glyph_payload_size(width: usize, height: usize) -> usize {
|
||||||
(width * height).div_ceil(2) + (GLYPH_BANK_PALETTE_COUNT_V1 * 16 * std::mem::size_of::<u32>())
|
(width * height).div_ceil(2)
|
||||||
|
+ (GLYPH_BANK_MAX_PALETTE_COUNT_V1 * 16 * std::mem::size_of::<u32>())
|
||||||
}
|
}
|
||||||
|
|
||||||
fn test_glyph_decoded_size(width: usize, height: usize) -> usize {
|
fn test_glyph_decoded_size(width: usize, height: usize) -> usize {
|
||||||
width * height + (GLYPH_BANK_PALETTE_COUNT_V1 * 16 * std::mem::size_of::<u32>())
|
width * height + (GLYPH_BANK_MAX_PALETTE_COUNT_V1 * 16 * std::mem::size_of::<u32>())
|
||||||
}
|
}
|
||||||
|
|
||||||
fn test_glyph_asset_entry(asset_name: &str, data_len: usize) -> AssetEntry {
|
fn test_glyph_asset_entry(asset_name: &str, data_len: usize) -> AssetEntry {
|
||||||
@@ -133,23 +134,23 @@ fn test_glyph_asset_entry(asset_name: &str, data_len: usize) -> AssetEntry {
|
|||||||
"tile_size": 16,
|
"tile_size": 16,
|
||||||
"width": 16,
|
"width": 16,
|
||||||
"height": 16,
|
"height": 16,
|
||||||
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
|
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||||
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
|
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
|
||||||
}),
|
}),
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
fn test_glyph_asset_data() -> Vec<u8> {
|
fn test_glyph_asset_data() -> Vec<u8> {
|
||||||
let mut data =
|
let mut data =
|
||||||
vec![0x11u8; test_glyph_payload_size(16, 16) - (GLYPH_BANK_PALETTE_COUNT_V1 * 16 * 4)];
|
vec![0x11u8; test_glyph_payload_size(16, 16) - (GLYPH_BANK_MAX_PALETTE_COUNT_V1 * 16 * 4)];
|
||||||
data.extend_from_slice(&[0u8; GLYPH_BANK_PALETTE_COUNT_V1 * 16 * 4]);
|
data.extend_from_slice(&[0u8; GLYPH_BANK_MAX_PALETTE_COUNT_V1 * 16 * 4]);
|
||||||
data
|
data
|
||||||
}
|
}
|
||||||
|
|
||||||
fn runtime_test_glyph_bank(tile_size: TileSize, palette_id: u8, color: Color) -> GlyphBank {
|
fn runtime_test_glyph_bank(tile_size: TileSize, palette_id: u8, color: Color) -> GlyphBank {
|
||||||
let size = tile_size as usize;
|
let size = tile_size as usize;
|
||||||
let mut bank = GlyphBank::new(tile_size, size, size);
|
let mut bank = GlyphBank::with_palette_count(tile_size, size, size, palette_id as usize + 1);
|
||||||
bank.palettes[palette_id as usize][1] = color;
|
bank.palette_mut(palette_id).unwrap()[1] = color;
|
||||||
for pixel in &mut bank.pixel_indices {
|
for pixel in &mut bank.pixel_indices {
|
||||||
*pixel = 1;
|
*pixel = 1;
|
||||||
}
|
}
|
||||||
@@ -1275,6 +1276,53 @@ fn tick_composer_emit_sprite_operational_error_returns_status_not_crash() {
|
|||||||
assert_eq!(vm.operand_stack_top(1), vec![Value::Int64(ComposerOpStatus::BankInvalid as i64)]);
|
assert_eq!(vm.operand_stack_top(1), vec![Value::Int64(ComposerOpStatus::BankInvalid as i64)]);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn tick_composer_emit_sprite_invalid_palette_returns_bank_invalid() {
|
||||||
|
let mut runtime = VirtualMachineRuntime::new(None);
|
||||||
|
let mut log_service = LogService::new(4096);
|
||||||
|
let mut fs = VirtualFS::new();
|
||||||
|
let mut fs_state = FsState::Unmounted;
|
||||||
|
let mut memcard = MemcardService::new();
|
||||||
|
let mut open_files: HashMap<u32, String> = HashMap::new();
|
||||||
|
let mut next_handle = 1;
|
||||||
|
let mut vm = VirtualMachine::default();
|
||||||
|
let banks = Arc::new(MemoryBanks::new());
|
||||||
|
banks.install_glyph_bank(0, Arc::new(runtime_test_glyph_bank(TileSize::Size8, 0, Color::BLUE)));
|
||||||
|
let mut platform = TestPlatform::new_with_memory_banks(banks);
|
||||||
|
let signals = InputSignals::default();
|
||||||
|
let code = assemble(
|
||||||
|
"PUSH_I32 0\nPUSH_I32 1\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 0\nPUSH_BOOL 0\nPUSH_BOOL 0\nPUSH_I32 0\nHOSTCALL 0\nHALT",
|
||||||
|
)
|
||||||
|
.expect("assemble");
|
||||||
|
let program = serialized_single_function_module(
|
||||||
|
code,
|
||||||
|
vec![SyscallDecl {
|
||||||
|
module: "composer".into(),
|
||||||
|
name: "emit_sprite".into(),
|
||||||
|
version: 1,
|
||||||
|
arg_slots: 9,
|
||||||
|
ret_slots: 1,
|
||||||
|
}],
|
||||||
|
);
|
||||||
|
let cartridge = cartridge_with_program(program, caps::GFX);
|
||||||
|
|
||||||
|
runtime.initialize_vm(&mut log_service, &mut vm, &cartridge).expect("runtime must initialize");
|
||||||
|
let report = runtime.tick(
|
||||||
|
&mut log_service,
|
||||||
|
&mut fs,
|
||||||
|
&mut fs_state,
|
||||||
|
&mut memcard,
|
||||||
|
&mut open_files,
|
||||||
|
&mut next_handle,
|
||||||
|
&mut vm,
|
||||||
|
&signals,
|
||||||
|
&mut platform,
|
||||||
|
);
|
||||||
|
assert!(report.is_none(), "invalid palette must not crash VM execution");
|
||||||
|
assert!(vm.is_halted());
|
||||||
|
assert_eq!(vm.operand_stack_top(1), vec![Value::Int64(ComposerOpStatus::BankInvalid as i64)]);
|
||||||
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn tick_composer_emit_sprite_invalid_layer_returns_status_not_crash() {
|
fn tick_composer_emit_sprite_invalid_layer_returns_status_not_crash() {
|
||||||
let mut runtime = VirtualMachineRuntime::new(None);
|
let mut runtime = VirtualMachineRuntime::new(None);
|
||||||
|
|||||||
@@ -2627,7 +2627,7 @@ mod tests {
|
|||||||
fn test_loader_hardening_unsupported_version() {
|
fn test_loader_hardening_unsupported_version() {
|
||||||
let mut vm = VirtualMachine::default();
|
let mut vm = VirtualMachine::default();
|
||||||
let mut header = vec![0u8; 32];
|
let mut header = vec![0u8; 32];
|
||||||
header[0..4].copy_from_slice(b"PBS\0");
|
header[0..4].copy_from_slice(&prometeu_bytecode::PBX_MAGIC);
|
||||||
header[4..6].copy_from_slice(&1u16.to_le_bytes()); // version 1 (unsupported)
|
header[4..6].copy_from_slice(&1u16.to_le_bytes()); // version 1 (unsupported)
|
||||||
|
|
||||||
let res = vm.initialize(header);
|
let res = vm.initialize(header);
|
||||||
@@ -2635,16 +2635,16 @@ mod tests {
|
|||||||
}
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn test_loader_hardening_malformed_pbs_v0() {
|
fn test_loader_hardening_malformed_pbx_v0() {
|
||||||
let mut vm = VirtualMachine::default();
|
let mut vm = VirtualMachine::default();
|
||||||
let mut header = vec![0u8; 32];
|
let mut header = vec![0u8; 32];
|
||||||
header[0..4].copy_from_slice(b"PBS\0");
|
header[0..4].copy_from_slice(&prometeu_bytecode::PBX_MAGIC);
|
||||||
header[8..12].copy_from_slice(&1u32.to_le_bytes()); // 1 section claimed but none provided
|
header[8..12].copy_from_slice(&1u32.to_le_bytes()); // 1 section claimed but none provided
|
||||||
|
|
||||||
let res = vm.initialize(header);
|
let res = vm.initialize(header);
|
||||||
match res {
|
match res {
|
||||||
Err(VmInitError::ImageLoadFailed(prometeu_bytecode::LoadError::UnexpectedEof)) => {}
|
Err(VmInitError::ImageLoadFailed(prometeu_bytecode::LoadError::UnexpectedEof)) => {}
|
||||||
_ => panic!("Expected PbsV0LoadFailed(UnexpectedEof), got {:?}", res),
|
_ => panic!("Expected PBX v0 load failure UnexpectedEof, got {:?}", res),
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -2695,6 +2695,13 @@ mod tests {
|
|||||||
assert_eq!(vm.pc, 0);
|
assert_eq!(vm.pc, 0);
|
||||||
assert_eq!(vm.program.rom.len(), 2);
|
assert_eq!(vm.program.rom.len(), 2);
|
||||||
assert_eq!(vm.cycles, 0);
|
assert_eq!(vm.cycles, 0);
|
||||||
|
|
||||||
|
vm.prepare_boot_call();
|
||||||
|
let mut native = MockNative;
|
||||||
|
let mut ctx = HostContext::new(None);
|
||||||
|
let report = vm.run_budget(100, &mut native, &mut ctx).expect("run loaded PBX");
|
||||||
|
assert_eq!(report.reason, LogicalFrameEndingReason::Halted);
|
||||||
|
assert!(vm.is_halted());
|
||||||
}
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
@@ -3084,7 +3091,7 @@ mod tests {
|
|||||||
fn test_loader_hardening_missing_sysc_section() {
|
fn test_loader_hardening_missing_sysc_section() {
|
||||||
let mut vm = VirtualMachine::default();
|
let mut vm = VirtualMachine::default();
|
||||||
let mut header = vec![0u8; 32];
|
let mut header = vec![0u8; 32];
|
||||||
header[0..4].copy_from_slice(b"PBS\0");
|
header[0..4].copy_from_slice(&prometeu_bytecode::PBX_MAGIC);
|
||||||
|
|
||||||
let res = vm.initialize(header);
|
let res = vm.initialize(header);
|
||||||
|
|
||||||
|
|||||||
@@ -83,8 +83,7 @@ impl VirtualMachine {
|
|||||||
self.scheduler = Scheduler::new();
|
self.scheduler = Scheduler::new();
|
||||||
self.current_coro = None;
|
self.current_coro = None;
|
||||||
|
|
||||||
let program = if program_bytes.starts_with(b"PBS\0") {
|
let program = match prometeu_bytecode::BytecodeLoader::load(&program_bytes) {
|
||||||
match prometeu_bytecode::BytecodeLoader::load(&program_bytes) {
|
|
||||||
Ok(mut module) => {
|
Ok(mut module) => {
|
||||||
patch_module_hostcalls(&mut module, self.capabilities)
|
patch_module_hostcalls(&mut module, self.capabilities)
|
||||||
.map_err(VmInitError::LoaderPatchFailed)?;
|
.map_err(VmInitError::LoaderPatchFailed)?;
|
||||||
@@ -103,10 +102,13 @@ impl VirtualMachine {
|
|||||||
Err(prometeu_bytecode::LoadError::InvalidVersion) => {
|
Err(prometeu_bytecode::LoadError::InvalidVersion) => {
|
||||||
return Err(VmInitError::UnsupportedFormat);
|
return Err(VmInitError::UnsupportedFormat);
|
||||||
}
|
}
|
||||||
Err(e) => return Err(VmInitError::ImageLoadFailed(e)),
|
Err(prometeu_bytecode::LoadError::InvalidMagic) => {
|
||||||
}
|
|
||||||
} else {
|
|
||||||
return Err(VmInitError::InvalidFormat);
|
return Err(VmInitError::InvalidFormat);
|
||||||
|
}
|
||||||
|
Err(prometeu_bytecode::LoadError::UnexpectedEof) if program_bytes.len() < 32 => {
|
||||||
|
return Err(VmInitError::InvalidFormat);
|
||||||
|
}
|
||||||
|
Err(e) => return Err(VmInitError::ImageLoadFailed(e)),
|
||||||
};
|
};
|
||||||
|
|
||||||
let pc = program
|
let pc = program
|
||||||
|
|||||||
@@ -2,8 +2,8 @@ use prometeu_vm::{VirtualMachine, VmInitError};
|
|||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn invalid_image_format_is_rejected_before_execution() {
|
fn invalid_image_format_is_rejected_before_execution() {
|
||||||
// Provide bytes that are not a valid PBS image. The VM must reject it with InvalidFormat.
|
// Provide bytes that are not a valid PBX image. The VM must reject it with InvalidFormat.
|
||||||
let program_bytes = b"NOT_PBS_IMAGE".to_vec();
|
let program_bytes = b"NOT_PBX_IMAGE".to_vec();
|
||||||
let mut vm = VirtualMachine::default();
|
let mut vm = VirtualMachine::default();
|
||||||
let result = vm.initialize(program_bytes);
|
let result = vm.initialize(program_bytes);
|
||||||
assert!(matches!(result, Err(VmInitError::InvalidFormat)));
|
assert!(matches!(result, Err(VmInitError::InvalidFormat)));
|
||||||
|
|||||||
@@ -0,0 +1,74 @@
|
|||||||
|
use std::fs;
|
||||||
|
use std::path::{Path, PathBuf};
|
||||||
|
|
||||||
|
const TARGET_MANIFESTS: &[&str] =
|
||||||
|
&["crates/console/prometeu-bytecode/Cargo.toml", "crates/console/prometeu-vm/Cargo.toml"];
|
||||||
|
|
||||||
|
const FORBIDDEN_DEPENDENCY_FRAGMENTS: &[&str] = &["compiler", "frontend"];
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn pbx_and_pvm_crates_must_not_depend_on_compiler_or_frontend_crates() {
|
||||||
|
let workspace_root = find_workspace_root().expect("runtime workspace root");
|
||||||
|
let mut violations = Vec::new();
|
||||||
|
|
||||||
|
for relative_path in TARGET_MANIFESTS {
|
||||||
|
let manifest_path = workspace_root.join(relative_path);
|
||||||
|
let manifest = fs::read_to_string(&manifest_path)
|
||||||
|
.unwrap_or_else(|error| panic!("failed to read {}: {error}", manifest_path.display()));
|
||||||
|
|
||||||
|
for dependency in dependency_names(&manifest) {
|
||||||
|
let normalized = dependency.to_ascii_lowercase();
|
||||||
|
if FORBIDDEN_DEPENDENCY_FRAGMENTS.iter().any(|fragment| normalized.contains(fragment)) {
|
||||||
|
violations.push(format!("{relative_path}: forbidden dependency `{dependency}`"));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
assert!(
|
||||||
|
violations.is_empty(),
|
||||||
|
"PBX/PVM crates must remain independent of compiler and frontend crates:\n{}",
|
||||||
|
violations.join("\n")
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
fn dependency_names(manifest: &str) -> Vec<&str> {
|
||||||
|
let mut names = Vec::new();
|
||||||
|
let mut in_dependency_section = false;
|
||||||
|
|
||||||
|
for raw_line in manifest.lines() {
|
||||||
|
let line = raw_line.trim();
|
||||||
|
if line.starts_with('[') && line.ends_with(']') {
|
||||||
|
let section = &line[1..line.len() - 1];
|
||||||
|
in_dependency_section = section == "dependencies"
|
||||||
|
|| section == "dev-dependencies"
|
||||||
|
|| section == "build-dependencies"
|
||||||
|
|| section.ends_with(".dependencies")
|
||||||
|
|| section.ends_with(".dev-dependencies")
|
||||||
|
|| section.ends_with(".build-dependencies");
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
|
||||||
|
if !in_dependency_section || line.is_empty() || line.starts_with('#') {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
|
||||||
|
if let Some((name, _)) = line.split_once('=') {
|
||||||
|
names.push(name.trim().trim_matches('"'));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
names
|
||||||
|
}
|
||||||
|
|
||||||
|
fn find_workspace_root() -> Option<PathBuf> {
|
||||||
|
let mut cursor = Path::new(env!("CARGO_MANIFEST_DIR")).to_path_buf();
|
||||||
|
loop {
|
||||||
|
let manifest = cursor.join("Cargo.toml");
|
||||||
|
if fs::read_to_string(&manifest).is_ok_and(|contents| contents.contains("[workspace]")) {
|
||||||
|
return Some(cursor);
|
||||||
|
}
|
||||||
|
if !cursor.pop() {
|
||||||
|
return None;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -26,16 +26,22 @@ const IDLE_HOST_POLL_DT: Duration = Duration::from_millis(100);
|
|||||||
|
|
||||||
#[derive(Debug, Clone)]
|
#[derive(Debug, Clone)]
|
||||||
struct PresentationState {
|
struct PresentationState {
|
||||||
latest_published_frame: u64,
|
latest_published_frame: Option<PresentationFrameMarker>,
|
||||||
last_presented_frame: Option<u64>,
|
last_presented_frame: Option<PresentationFrameMarker>,
|
||||||
host_invalidated: bool,
|
host_invalidated: bool,
|
||||||
redraw_requested: bool,
|
redraw_requested: bool,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||||
|
struct PresentationFrameMarker {
|
||||||
|
ownership: RenderOwnership,
|
||||||
|
frame_id: u64,
|
||||||
|
}
|
||||||
|
|
||||||
impl Default for PresentationState {
|
impl Default for PresentationState {
|
||||||
fn default() -> Self {
|
fn default() -> Self {
|
||||||
Self {
|
Self {
|
||||||
latest_published_frame: 0,
|
latest_published_frame: None,
|
||||||
last_presented_frame: None,
|
last_presented_frame: None,
|
||||||
host_invalidated: true,
|
host_invalidated: true,
|
||||||
redraw_requested: false,
|
redraw_requested: false,
|
||||||
@@ -44,9 +50,10 @@ impl Default for PresentationState {
|
|||||||
}
|
}
|
||||||
|
|
||||||
impl PresentationState {
|
impl PresentationState {
|
||||||
fn note_published_frame(&mut self, frame_index: u64) {
|
fn note_published_frame(&mut self, ownership: RenderOwnership, frame_id: u64) {
|
||||||
if frame_index > self.latest_published_frame {
|
let marker = PresentationFrameMarker { ownership, frame_id };
|
||||||
self.latest_published_frame = frame_index;
|
if self.latest_published_frame != Some(marker) {
|
||||||
|
self.latest_published_frame = Some(marker);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -55,7 +62,7 @@ impl PresentationState {
|
|||||||
}
|
}
|
||||||
|
|
||||||
fn needs_redraw(&self) -> bool {
|
fn needs_redraw(&self) -> bool {
|
||||||
self.host_invalidated || self.last_presented_frame != Some(self.latest_published_frame)
|
self.host_invalidated || self.last_presented_frame != self.latest_published_frame
|
||||||
}
|
}
|
||||||
|
|
||||||
fn should_request_redraw(&mut self) -> bool {
|
fn should_request_redraw(&mut self) -> bool {
|
||||||
@@ -70,7 +77,7 @@ impl PresentationState {
|
|||||||
fn mark_presented(&mut self) {
|
fn mark_presented(&mut self) {
|
||||||
self.redraw_requested = false;
|
self.redraw_requested = false;
|
||||||
self.host_invalidated = false;
|
self.host_invalidated = false;
|
||||||
self.last_presented_frame = Some(self.latest_published_frame);
|
self.last_presented_frame = self.latest_published_frame;
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -437,9 +444,11 @@ impl ApplicationHandler for HostRunner {
|
|||||||
if let Some(worker_frame) = self.render_frame_store.latest_frame()
|
if let Some(worker_frame) = self.render_frame_store.latest_frame()
|
||||||
&& should_present_worker_frame(&self.firmware.state, &worker_frame, active_ownership)
|
&& should_present_worker_frame(&self.firmware.state, &worker_frame, active_ownership)
|
||||||
{
|
{
|
||||||
self.presentation.note_published_frame(worker_frame.frame_id.get());
|
self.presentation
|
||||||
|
.note_published_frame(worker_frame.ownership, worker_frame.frame_id.get());
|
||||||
} else {
|
} else {
|
||||||
self.presentation.note_published_frame(self.firmware.os.frame_index());
|
self.presentation
|
||||||
|
.note_published_frame(active_ownership, self.firmware.os.frame_index());
|
||||||
}
|
}
|
||||||
|
|
||||||
if was_debugger_connected != self.debugger.stream.is_some()
|
if was_debugger_connected != self.debugger.stream.is_some()
|
||||||
@@ -505,14 +514,37 @@ mod tests {
|
|||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
fn presentation_state_requests_redraw_for_new_frame_publication() {
|
fn presentation_state_requests_redraw_for_new_frame_publication() {
|
||||||
|
let ownership = RenderOwnership::new(1, AppMode::Game, 1);
|
||||||
let mut state = PresentationState::default();
|
let mut state = PresentationState::default();
|
||||||
state.mark_presented();
|
state.mark_presented();
|
||||||
|
|
||||||
state.note_published_frame(1);
|
state.note_published_frame(ownership, 1);
|
||||||
|
|
||||||
assert!(state.should_request_redraw());
|
assert!(state.should_request_redraw());
|
||||||
state.mark_presented();
|
state.mark_presented();
|
||||||
assert_eq!(state.last_presented_frame, Some(1));
|
assert_eq!(
|
||||||
|
state.last_presented_frame,
|
||||||
|
Some(PresentationFrameMarker { ownership, frame_id: 1 })
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn presentation_state_requests_redraw_when_ownership_changes_with_lower_frame_id() {
|
||||||
|
let first = RenderOwnership::new(3, AppMode::Game, 1);
|
||||||
|
let next = RenderOwnership::new(4, AppMode::Game, 2);
|
||||||
|
let mut state = PresentationState::default();
|
||||||
|
|
||||||
|
state.note_published_frame(first, 120);
|
||||||
|
state.mark_presented();
|
||||||
|
|
||||||
|
state.note_published_frame(next, 0);
|
||||||
|
|
||||||
|
assert!(state.should_request_redraw());
|
||||||
|
state.mark_presented();
|
||||||
|
assert_eq!(
|
||||||
|
state.last_presented_frame,
|
||||||
|
Some(PresentationFrameMarker { ownership: next, frame_id: 0 })
|
||||||
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
@@ -608,11 +640,14 @@ mod tests {
|
|||||||
let mut presentation = PresentationState::default();
|
let mut presentation = PresentationState::default();
|
||||||
presentation.mark_presented();
|
presentation.mark_presented();
|
||||||
let published = store.latest_frame().expect("published frame");
|
let published = store.latest_frame().expect("published frame");
|
||||||
presentation.note_published_frame(published.frame_id.get());
|
presentation.note_published_frame(published.ownership, published.frame_id.get());
|
||||||
|
|
||||||
assert!(presentation.should_request_redraw());
|
assert!(presentation.should_request_redraw());
|
||||||
presentation.mark_presented();
|
presentation.mark_presented();
|
||||||
assert_eq!(presentation.last_presented_frame, Some(9));
|
assert_eq!(
|
||||||
|
presentation.last_presented_frame,
|
||||||
|
Some(PresentationFrameMarker { ownership: published.ownership, frame_id: 9 })
|
||||||
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
#[test]
|
#[test]
|
||||||
|
|||||||
@@ -0,0 +1,12 @@
|
|||||||
|
[package]
|
||||||
|
name = "pbxgen-dummy-boy"
|
||||||
|
version = "0.1.0"
|
||||||
|
edition = "2021"
|
||||||
|
|
||||||
|
[dependencies]
|
||||||
|
anyhow = "1"
|
||||||
|
prometeu-bytecode = { path = "../../console/prometeu-bytecode" }
|
||||||
|
prometeu-hal = { path = "../../console/prometeu-hal" }
|
||||||
|
|
||||||
|
[dev-dependencies]
|
||||||
|
serde_json = "1"
|
||||||
@@ -0,0 +1,147 @@
|
|||||||
|
use anyhow::Result;
|
||||||
|
use prometeu_bytecode::assembler::assemble;
|
||||||
|
use prometeu_bytecode::model::{BytecodeModule, DebugInfo, Export, FunctionMeta, SyscallDecl};
|
||||||
|
use prometeu_hal::color::Color;
|
||||||
|
use std::fs;
|
||||||
|
use std::path::PathBuf;
|
||||||
|
|
||||||
|
const APP_ID: u32 = 2;
|
||||||
|
const TITLE: &str = "Dummy Boy";
|
||||||
|
const APP_VERSION: &str = "0.1.0";
|
||||||
|
|
||||||
|
fn asm(s: &str) -> Vec<u8> {
|
||||||
|
assemble(s).expect("assemble")
|
||||||
|
}
|
||||||
|
|
||||||
|
pub fn generate() -> Result<()> {
|
||||||
|
let out_dir = cartridge_dir();
|
||||||
|
fs::create_dir_all(&out_dir)?;
|
||||||
|
fs::write(out_dir.join("program.pbx"), build_program())?;
|
||||||
|
fs::write(out_dir.join("manifest.json"), manifest_json())?;
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
pub fn build_program() -> Vec<u8> {
|
||||||
|
let mut rom = Vec::new();
|
||||||
|
|
||||||
|
rom.extend(asm("GET_GLOBAL 0\nPUSH_I32 1\nADD\nSET_GLOBAL 0"));
|
||||||
|
rom.extend(asm(&format!("PUSH_I64 {}\nHOSTCALL 0", Color::BLACK.raw())));
|
||||||
|
|
||||||
|
rom.extend(asm("GET_GLOBAL 0\nPUSH_I32 3\nMOD\nPUSH_I32 0\nEQ"));
|
||||||
|
let jump_to_green_case_offset = rom.len() + 2;
|
||||||
|
rom.extend(asm("JMP_IF_FALSE 0"));
|
||||||
|
rom.extend(asm(&format!("PUSH_I64 {}\nSET_LOCAL 0", Color::RED.raw())));
|
||||||
|
let jump_to_draw_after_red_offset = rom.len() + 2;
|
||||||
|
rom.extend(asm("JMP 0"));
|
||||||
|
|
||||||
|
let green_case = rom.len() as u32;
|
||||||
|
rom.extend(asm("GET_GLOBAL 0\nPUSH_I32 3\nMOD\nPUSH_I32 1\nEQ"));
|
||||||
|
let jump_to_blue_case_offset = rom.len() + 2;
|
||||||
|
rom.extend(asm("JMP_IF_FALSE 0"));
|
||||||
|
rom.extend(asm(&format!("PUSH_I64 {}\nSET_LOCAL 0", Color::GREEN.raw())));
|
||||||
|
let jump_to_draw_after_green_offset = rom.len() + 2;
|
||||||
|
rom.extend(asm("JMP 0"));
|
||||||
|
|
||||||
|
let blue_case = rom.len() as u32;
|
||||||
|
rom.extend(asm(&format!("PUSH_I64 {}\nSET_LOCAL 0", Color::BLUE.raw())));
|
||||||
|
|
||||||
|
let draw = rom.len() as u32;
|
||||||
|
rom.extend(asm(&format!(
|
||||||
|
"PUSH_I32 180\n\
|
||||||
|
PUSH_I32 75\n\
|
||||||
|
PUSH_I32 120\n\
|
||||||
|
PUSH_I32 120\n\
|
||||||
|
PUSH_I64 {}\n\
|
||||||
|
GET_LOCAL 0\n\
|
||||||
|
HOSTCALL 1\n\
|
||||||
|
FRAME_SYNC\n\
|
||||||
|
RET",
|
||||||
|
Color::WHITE.raw()
|
||||||
|
)));
|
||||||
|
|
||||||
|
patch_jump(&mut rom, jump_to_green_case_offset, green_case);
|
||||||
|
patch_jump(&mut rom, jump_to_draw_after_red_offset, draw);
|
||||||
|
patch_jump(&mut rom, jump_to_blue_case_offset, blue_case);
|
||||||
|
patch_jump(&mut rom, jump_to_draw_after_green_offset, draw);
|
||||||
|
|
||||||
|
BytecodeModule {
|
||||||
|
version: 0,
|
||||||
|
const_pool: vec![],
|
||||||
|
functions: vec![FunctionMeta {
|
||||||
|
code_offset: 0,
|
||||||
|
code_len: rom.len() as u32,
|
||||||
|
param_slots: 0,
|
||||||
|
local_slots: 1,
|
||||||
|
return_slots: 0,
|
||||||
|
max_stack_slots: 8,
|
||||||
|
}],
|
||||||
|
code: rom,
|
||||||
|
debug_info: Some(DebugInfo {
|
||||||
|
pc_to_span: vec![],
|
||||||
|
function_names: vec![(0, "main".into())],
|
||||||
|
}),
|
||||||
|
exports: vec![Export { symbol: "main".into(), func_idx: 0 }],
|
||||||
|
syscalls: vec![
|
||||||
|
SyscallDecl {
|
||||||
|
module: "gfx2d".into(),
|
||||||
|
name: "clear".into(),
|
||||||
|
version: 1,
|
||||||
|
arg_slots: 1,
|
||||||
|
ret_slots: 0,
|
||||||
|
},
|
||||||
|
SyscallDecl {
|
||||||
|
module: "gfx2d".into(),
|
||||||
|
name: "draw_square".into(),
|
||||||
|
version: 1,
|
||||||
|
arg_slots: 6,
|
||||||
|
ret_slots: 0,
|
||||||
|
},
|
||||||
|
],
|
||||||
|
}
|
||||||
|
.serialize()
|
||||||
|
}
|
||||||
|
|
||||||
|
pub fn manifest_json() -> Vec<u8> {
|
||||||
|
format!(
|
||||||
|
"{{\n \"magic\": \"PMTU\",\n \"cartridge_version\": 1,\n \"app_id\": {APP_ID},\n \"title\": \"{TITLE}\",\n \"app_version\": \"{APP_VERSION}\",\n \"app_mode\": \"Game\",\n \"capabilities\": [\"gfx2d\"]\n}}\n"
|
||||||
|
)
|
||||||
|
.into_bytes()
|
||||||
|
}
|
||||||
|
|
||||||
|
fn cartridge_dir() -> PathBuf {
|
||||||
|
let mut out_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||||
|
out_dir.pop();
|
||||||
|
out_dir.pop();
|
||||||
|
out_dir.pop();
|
||||||
|
out_dir.push("test-cartridges");
|
||||||
|
out_dir.push("dummy-boy");
|
||||||
|
out_dir
|
||||||
|
}
|
||||||
|
|
||||||
|
fn patch_jump(buf: &mut [u8], imm_offset: usize, target: u32) {
|
||||||
|
buf[imm_offset..imm_offset + 4].copy_from_slice(&target.to_le_bytes());
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(test)]
|
||||||
|
mod tests {
|
||||||
|
use super::*;
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn generated_program_is_pbx_module_with_expected_syscalls() {
|
||||||
|
let bytes = build_program();
|
||||||
|
|
||||||
|
assert!(bytes.starts_with(&prometeu_bytecode::PBX_MAGIC));
|
||||||
|
assert!(bytes.len() > 64);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn manifest_declares_distinct_game_identity() {
|
||||||
|
let manifest: serde_json::Value =
|
||||||
|
serde_json::from_slice(&manifest_json()).expect("manifest should parse");
|
||||||
|
|
||||||
|
assert_eq!(manifest["app_id"], APP_ID);
|
||||||
|
assert_eq!(manifest["title"], TITLE);
|
||||||
|
assert_eq!(manifest["app_mode"], "Game");
|
||||||
|
assert_eq!(manifest["capabilities"], serde_json::json!(["gfx2d"]));
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,5 @@
|
|||||||
|
use anyhow::Result;
|
||||||
|
|
||||||
|
fn main() -> Result<()> {
|
||||||
|
pbxgen_dummy_boy::generate()
|
||||||
|
}
|
||||||
@@ -14,7 +14,7 @@ use prometeu_hal::cartridge::{
|
|||||||
use prometeu_hal::color::Color;
|
use prometeu_hal::color::Color;
|
||||||
use prometeu_hal::glyph::Glyph;
|
use prometeu_hal::glyph::Glyph;
|
||||||
use prometeu_hal::glyph_bank::{
|
use prometeu_hal::glyph_bank::{
|
||||||
TileSize, GLYPH_BANK_COLORS_PER_PALETTE, GLYPH_BANK_PALETTE_COUNT_V1,
|
TileSize, GLYPH_BANK_COLORS_PER_PALETTE, GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||||
};
|
};
|
||||||
use prometeu_hal::scene_bank::SceneBank;
|
use prometeu_hal::scene_bank::SceneBank;
|
||||||
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
|
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
|
||||||
@@ -275,15 +275,15 @@ fn build_glyph_asset() -> (AssetEntry, Vec<u8>) {
|
|||||||
bank_type: BankType::GLYPH,
|
bank_type: BankType::GLYPH,
|
||||||
offset: 0,
|
offset: 0,
|
||||||
size: payload.len() as u64,
|
size: payload.len() as u64,
|
||||||
decoded_size: (8 * 8 + GLYPH_BANK_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * 4)
|
decoded_size: (8 * 8 + GLYPH_BANK_MAX_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * 4)
|
||||||
as u64,
|
as u64,
|
||||||
codec: AssetCodec::None,
|
codec: AssetCodec::None,
|
||||||
metadata: serde_json::json!({
|
metadata: serde_json::json!({
|
||||||
"tile_size": 8,
|
"tile_size": 8,
|
||||||
"width": 8,
|
"width": 8,
|
||||||
"height": 8,
|
"height": 8,
|
||||||
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
|
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||||
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
|
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
|
||||||
}),
|
}),
|
||||||
};
|
};
|
||||||
|
|
||||||
@@ -292,8 +292,8 @@ fn build_glyph_asset() -> (AssetEntry, Vec<u8>) {
|
|||||||
|
|
||||||
fn build_palette_bytes() -> Vec<u8> {
|
fn build_palette_bytes() -> Vec<u8> {
|
||||||
let mut bytes =
|
let mut bytes =
|
||||||
Vec::with_capacity(GLYPH_BANK_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * 4);
|
Vec::with_capacity(GLYPH_BANK_MAX_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * 4);
|
||||||
for palette_id in 0..GLYPH_BANK_PALETTE_COUNT_V1 {
|
for palette_id in 0..GLYPH_BANK_MAX_PALETTE_COUNT_V1 {
|
||||||
for color_index in 0..GLYPH_BANK_COLORS_PER_PALETTE {
|
for color_index in 0..GLYPH_BANK_COLORS_PER_PALETTE {
|
||||||
let color = if color_index == 1 { stress_color(palette_id) } else { Color::BLACK };
|
let color = if color_index == 1 { stress_color(palette_id) } else { Color::BLACK };
|
||||||
bytes.extend_from_slice(&color.raw().to_be_bytes());
|
bytes.extend_from_slice(&color.raw().to_be_bytes());
|
||||||
|
|||||||
@@ -1,5 +1,6 @@
|
|||||||
{"type":"meta","next_id":{"DSC":44,"AGD":47,"DEC":40,"PLN":163,"LSN":53,"CLSN":1}}
|
{"type":"meta","next_id":{"DSC":49,"AGD":52,"DEC":43,"PLN":174,"LSN":57,"CLSN":1}}
|
||||||
{"type":"discussion","id":"DSC-0043","status":"in_progress","ticket":"system-os-cartridge-switch-orchestrator","title":"SystemOS Cartridge Switch Orchestrator","created_at":"2026-07-03","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","game","cartridge","architecture"],"agendas":[{"id":"AGD-0044","file":"AGD-0044-systemos-cartridge-switch-orchestrator.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-05"}],"decisions":[{"id":"DEC-0039","file":"DEC-0039-systemos-game-cartridge-switch-orchestrator.md","status":"accepted","created_at":"2026-07-05","updated_at":"2026-07-05","ref_agenda":"AGD-0044"}],"plans":[{"id":"PLN-0157","file":"PLN-0157-introduce-systemos-game-switch-target-contract.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05","ref_decisions":["DEC-0039"]},{"id":"PLN-0158","file":"PLN-0158-terminate-resident-game-before-switching-cartridges.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05","ref_decisions":["DEC-0039"]},{"id":"PLN-0159","file":"PLN-0159-recover-failed-game-switches-back-to-home.md","status":"open","created_at":"2026-07-05","updated_at":"2026-07-05","ref_decisions":["DEC-0039"]},{"id":"PLN-0160","file":"PLN-0160-add-dummy-boy-visual-switch-test-cartridge.md","status":"open","created_at":"2026-07-05","updated_at":"2026-07-05","ref_decisions":["DEC-0039"]},{"id":"PLN-0161","file":"PLN-0161-validate-stress-to-dummy-boy-game-switch-end-to-end.md","status":"open","created_at":"2026-07-05","updated_at":"2026-07-05","ref_decisions":["DEC-0039"]},{"id":"PLN-0162","file":"PLN-0162-specify-game-switch-contract-and-direct-boot-separation.md","status":"open","created_at":"2026-07-05","updated_at":"2026-07-05","ref_decisions":["DEC-0039"]}],"lessons":[]}
|
{"type":"discussion","id":"DSC-0044","status":"done","ticket":"hub-suspended-game-kill-affordance","title":"Hub Suspended Game Kill Affordance","created_at":"2026-07-05","updated_at":"2026-07-05","tags":["hub","lifecycle","game","ui"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0054","file":"discussion/lessons/DSC-0044-hub-suspended-game-kill-affordance/LSN-0054-manual-hub-kill-must-share-game-termination-cleanup.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]}
|
||||||
|
{"type":"discussion","id":"DSC-0043","status":"done","ticket":"system-os-cartridge-switch-orchestrator","title":"SystemOS Cartridge Switch Orchestrator","created_at":"2026-07-03","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","game","cartridge","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0053","file":"discussion/lessons/DSC-0043-system-os-cartridge-switch-orchestrator/LSN-0053-game-switching-is-lifecycle-replacement-not-loader-work.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]}
|
||||||
{"type":"discussion","id":"DSC-0039","status":"abandoned","ticket":"render-pipeline-family-and-future-3d","title":"Render Pipeline Family and Future 3D","created_at":"2026-06-04","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","architecture","pipeline"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-render-pipeline-family-and-future-3d.md","status":"abandoned","created_at":"2026-06-04","updated_at":"2026-06-04","_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}
|
{"type":"discussion","id":"DSC-0039","status":"abandoned","ticket":"render-pipeline-family-and-future-3d","title":"Render Pipeline Family and Future 3D","created_at":"2026-06-04","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","architecture","pipeline"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-render-pipeline-family-and-future-3d.md","status":"abandoned","created_at":"2026-06-04","updated_at":"2026-06-04","_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}
|
||||||
{"type":"discussion","id":"DSC-0040","status":"done","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-06","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-06"}]}
|
{"type":"discussion","id":"DSC-0040","status":"done","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-06","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-06"}]}
|
||||||
{"type":"discussion","id":"DSC-0041","status":"done","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0052","file":"discussion/lessons/DSC-0041-foreground-stack-game-pause-shell-vm-backed/LSN-0052-foreground-ownership-and-vm-session-ownership-are-separate.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]}
|
{"type":"discussion","id":"DSC-0041","status":"done","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0052","file":"discussion/lessons/DSC-0041-foreground-stack-game-pause-shell-vm-backed/LSN-0052-foreground-ownership-and-vm-session-ownership-are-separate.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]}
|
||||||
@@ -18,6 +19,7 @@
|
|||||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||||
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||||
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||||
|
{"type":"discussion","id":"DSC-0045","status":"open","ticket":"background-service-audio-execution","title":"Background Service and Audio Execution","created_at":"2026-07-05","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","service","audio","background","architecture"],"agendas":[{"id":"AGD-0048","file":"AGD-0048-background-service-audio-execution.md","status":"open","created_at":"2026-07-05","updated_at":"2026-07-05"}],"decisions":[],"plans":[],"lessons":[]}
|
||||||
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-06-04","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0008-perf-runtime-telemetry-hot-path/LSN-0026-push-based-telemetry-model.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-06-04","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0008-perf-runtime-telemetry-hot-path/LSN-0026-push-based-telemetry-model.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||||
{"type":"discussion","id":"DSC-0009","status":"done","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-07-01","tags":["perf","asset","fs","async","scheduler","runtime"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0050","file":"discussion/lessons/DSC-0009-perf-async-background-work-lanes-for-assets-and-fs/LSN-0050-serial-async-lanes-bound-backlog-complexity.md","status":"done","created_at":"2026-07-01","updated_at":"2026-07-01"}]}
|
{"type":"discussion","id":"DSC-0009","status":"done","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-07-01","tags":["perf","asset","fs","async","scheduler","runtime"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0050","file":"discussion/lessons/DSC-0009-perf-async-background-work-lanes-for-assets-and-fs/LSN-0050-serial-async-lanes-bound-backlog-complexity.md","status":"done","created_at":"2026-07-01","updated_at":"2026-07-01"}]}
|
||||||
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-04-20","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0010-perf-host-desktop-frame-pacing-and-presentation/LSN-0036-frame-publication-and-host-invalidation-must-be-separate.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-20"}]}
|
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-04-20","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0010-perf-host-desktop-frame-pacing-and-presentation/LSN-0036-frame-publication-and-host-invalidation-must-be-separate.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-20"}]}
|
||||||
@@ -42,3 +44,6 @@
|
|||||||
{"type":"discussion","id":"DSC-0033","status":"done","ticket":"system-os-service-ownership-and-module-layout","title":"Agenda - SystemOS Service Ownership and Module Layout","created_at":"2026-05-14","updated_at":"2026-05-15","tags":["runtime","os","services","module-layout","vm","window-manager","logging"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0042","file":"discussion/lessons/DSC-0033-system-os-service-ownership-and-module-layout/LSN-0042-systemos-service-ownership-boundary.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]}
|
{"type":"discussion","id":"DSC-0033","status":"done","ticket":"system-os-service-ownership-and-module-layout","title":"Agenda - SystemOS Service Ownership and Module Layout","created_at":"2026-05-14","updated_at":"2026-05-15","tags":["runtime","os","services","module-layout","vm","window-manager","logging"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0042","file":"discussion/lessons/DSC-0033-system-os-service-ownership-and-module-layout/LSN-0042-systemos-service-ownership-boundary.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]}
|
||||||
{"type":"discussion","id":"DSC-0036","status":"done","ticket":"prometeu-hub-ui-direction","title":"Agenda - Prometeu Hub UI Direction","created_at":"2026-05-15","updated_at":"2026-05-22","tags":["hub","ui","shell","system-apps","lifecycle","design-system"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0045","file":"discussion/lessons/DSC-0036-prometeu-hub-ui-direction/LSN-0045-hub-ui-slices-should-prove-os-boundaries.md","status":"done","created_at":"2026-05-22","updated_at":"2026-05-22"}]}
|
{"type":"discussion","id":"DSC-0036","status":"done","ticket":"prometeu-hub-ui-direction","title":"Agenda - Prometeu Hub UI Direction","created_at":"2026-05-15","updated_at":"2026-05-22","tags":["hub","ui","shell","system-apps","lifecycle","design-system"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0045","file":"discussion/lessons/DSC-0036-prometeu-hub-ui-direction/LSN-0045-hub-ui-slices-should-prove-os-boundaries.md","status":"done","created_at":"2026-05-22","updated_at":"2026-05-22"}]}
|
||||||
{"type":"discussion","id":"DSC-0037","status":"done","ticket":"rgba8888-framebuffer-and-pixel-format-direction","title":"Agenda - RGBA8888 Framebuffer and Pixel Format Direction","created_at":"2026-05-22","updated_at":"2026-05-23","tags":["gfx","framebuffer","rgb565","rgba8888","renderer","assets","host","backend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0046","file":"discussion/lessons/DSC-0037-rgba8888-framebuffer-and-pixel-format-direction/LSN-0046-pixel-format-contracts-must-move-as-one-surface.md","status":"done","created_at":"2026-05-23","updated_at":"2026-05-23"}]}
|
{"type":"discussion","id":"DSC-0037","status":"done","ticket":"rgba8888-framebuffer-and-pixel-format-direction","title":"Agenda - RGBA8888 Framebuffer and Pixel Format Direction","created_at":"2026-05-22","updated_at":"2026-05-23","tags":["gfx","framebuffer","rgb565","rgba8888","renderer","assets","host","backend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0046","file":"discussion/lessons/DSC-0037-rgba8888-framebuffer-and-pixel-format-direction/LSN-0046-pixel-format-contracts-must-move-as-one-surface.md","status":"done","created_at":"2026-05-23","updated_at":"2026-05-23"}]}
|
||||||
|
{"type":"discussion","id":"DSC-0046","status":"done","ticket":"runtime-owned-variable-glyph-bank-palette-protocol","title":"Runtime-Owned Variable Glyph Bank Palette Protocol","created_at":"2026-07-14","updated_at":"2026-07-14","tags":["runtime","gfx","assets","glyph-bank","palette-serialization","protocol"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0055","file":"discussion/lessons/DSC-0046-runtime-owned-variable-glyph-bank-palette-protocol/LSN-0055-runtime-owned-asset-protocols-must-align-payload-residency-and-lookup.md","status":"done","created_at":"2026-07-14","updated_at":"2026-07-14"}]}
|
||||||
|
{"type":"discussion","id":"DSC-0047","status":"open","ticket":"portable-host-backend-strategy","title":"Portable Host Backend Strategy","created_at":"2026-07-14","updated_at":"2026-07-14","tags":["host","desktop","portable","sdl","backend","rendering","input","audio","linux","android","handheld"],"agendas":[{"id":"AGD-0050","file":"AGD-0050-portable-host-backend-strategy.md","status":"open","created_at":"2026-07-14","updated_at":"2026-07-14"}],"decisions":[],"plans":[],"lessons":[]}
|
||||||
|
{"type":"discussion","id":"DSC-0048","status":"done","ticket":"corrigir-identificacao-formato-pbx","title":"Corrigir Identificacao do Formato PBX","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["runtime","bytecode","pbx","loader","format","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0056","file":"discussion/lessons/DSC-0048-corrigir-identificacao-formato-pbx/LSN-0056-runtime-artifact-identity-must-not-borrow-frontend-names.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
||||||
|
|||||||
+67
@@ -0,0 +1,67 @@
|
|||||||
|
---
|
||||||
|
id: LSN-0053
|
||||||
|
ticket: system-os-cartridge-switch-orchestrator
|
||||||
|
title: Game Switching Is Lifecycle Replacement, Not Loader Work
|
||||||
|
created: 2026-07-05
|
||||||
|
tags: [runtime, os, lifecycle, game, cartridge]
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
PROMETEU supports two superficially similar flows:
|
||||||
|
|
||||||
|
- `Game -> Home -> same Game`, which is pause/suspend/resume.
|
||||||
|
- `Game A -> Home -> Game B`, which is destructive replacement.
|
||||||
|
|
||||||
|
The second flow is not a loader feature. It is a SystemOS lifecycle operation
|
||||||
|
that happens to use the cartridge loader after the old resident Game has been
|
||||||
|
removed from resumable state.
|
||||||
|
|
||||||
|
## Key Decisions
|
||||||
|
|
||||||
|
### SystemOS Game Cartridge Switch Orchestrator
|
||||||
|
|
||||||
|
**What:** A different-Game launch from Home terminates the previous resident
|
||||||
|
Game before loading the new cartridge. The new Game receives a fresh VM session.
|
||||||
|
|
||||||
|
**Why:** Reusing or preserving the old Game while the new Game loads creates a
|
||||||
|
rollback problem across VM state, handles, assets, input, audio, render
|
||||||
|
ownership, debug state, and lifecycle delivery. V1 does not need that
|
||||||
|
transactional model.
|
||||||
|
|
||||||
|
**Trade-offs:** Failed replacement returns to Home and does not restore the old
|
||||||
|
Game. This is intentionally simpler than snapshot/rollback and makes state
|
||||||
|
ownership visible in tests.
|
||||||
|
|
||||||
|
## Patterns and Algorithms
|
||||||
|
|
||||||
|
Use a resolved SystemOS switch target, not a guest syscall, for Home launches.
|
||||||
|
The target carries cartridge path and identity, while SystemOS owns the policy:
|
||||||
|
|
||||||
|
1. detect whether the selected Game matches the resident `app_id`;
|
||||||
|
2. resume if it is the same Game;
|
||||||
|
3. terminate the old resident Game if it is different;
|
||||||
|
4. load the new cartridge through the normal loader;
|
||||||
|
5. create and initialize a fresh VM session;
|
||||||
|
6. return to Home on replacement failure without restoring the previous Game.
|
||||||
|
|
||||||
|
The loader stays a materializer. It does not close tasks, remove sessions,
|
||||||
|
repair foreground state, or own failure recovery.
|
||||||
|
|
||||||
|
## Pitfalls
|
||||||
|
|
||||||
|
- Treating a different Game as a resume path leaks VM execution state.
|
||||||
|
- Letting the loader own lifecycle cleanup hides policy in the wrong layer.
|
||||||
|
- Keeping the old Game as rollback state requires correctness across assets,
|
||||||
|
render ownership, input barriers, audio, open handles, and debugger state.
|
||||||
|
- A switch test with only one cartridge cannot prove identity replacement.
|
||||||
|
|
||||||
|
## Takeaways
|
||||||
|
|
||||||
|
- Same-Game Home selection is resume; different-Game Home selection is
|
||||||
|
destructive replacement.
|
||||||
|
- SystemOS owns cartridge switching policy; the cartridge loader only loads.
|
||||||
|
- Replacement failure should be a clean Home state, not a rollback to the old
|
||||||
|
Game.
|
||||||
|
- End-to-end switch tests need visually distinct cartridges to catch stale
|
||||||
|
session or stale frame reuse.
|
||||||
+72
@@ -0,0 +1,72 @@
|
|||||||
|
---
|
||||||
|
id: LSN-0054
|
||||||
|
ticket: hub-suspended-game-kill-affordance
|
||||||
|
title: Manual Hub Kill Must Share Game Termination Cleanup
|
||||||
|
created: 2026-07-05
|
||||||
|
tags: [hub, lifecycle, game, ui, assets]
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
After a Game returns to Home, the Game can remain resident and suspended so it
|
||||||
|
can be resumed later. That state needs a visible, direct way to terminate the
|
||||||
|
resident Game without launching another cartridge just to force replacement.
|
||||||
|
|
||||||
|
The Hub kill affordance solved the UX gap, but the durable engineering lesson is
|
||||||
|
the cleanup boundary: manual kill must not become a second, partial termination
|
||||||
|
path.
|
||||||
|
|
||||||
|
## Key Decisions
|
||||||
|
|
||||||
|
### Hub Suspended Game Kill Affordance
|
||||||
|
|
||||||
|
**What:** Hub renders a red bottom-right control when a Game is resident and
|
||||||
|
suspended. The control shows only the Game title. Clicking it immediately
|
||||||
|
terminates the resident Game and keeps the user in Hub.
|
||||||
|
|
||||||
|
**Why:** The user can distinguish "resume this Game" from "discard this resident
|
||||||
|
Game" without starting a different cartridge. Reusing the canonical termination
|
||||||
|
path prevents a repeat of stale scene/glyph/asset state bugs.
|
||||||
|
|
||||||
|
**Trade-offs:** V1 has no confirmation step. The destructive nature is carried
|
||||||
|
by placement, color, and the fact that the target Game is already out of
|
||||||
|
foreground.
|
||||||
|
|
||||||
|
## Patterns and Algorithms
|
||||||
|
|
||||||
|
Manual Hub kill and destructive Game replacement should call the same resident
|
||||||
|
Game termination helper. That helper is responsible for the whole runtime
|
||||||
|
surface:
|
||||||
|
|
||||||
|
- close the Game task;
|
||||||
|
- stop the process;
|
||||||
|
- remove the VM session;
|
||||||
|
- clear resident Game state and task-scoped lifecycle delivery;
|
||||||
|
- restore Shell/Hub render ownership;
|
||||||
|
- clear lifecycle audio pause state;
|
||||||
|
- unbind the Game2D composer scene;
|
||||||
|
- shut down cartridge-scoped asset manager state and physical banks;
|
||||||
|
- emit explicit Hub/POS observability for manual kill.
|
||||||
|
|
||||||
|
The Hub itself should emit a high-level action such as `KillResidentGame`; it
|
||||||
|
should not know how to clean runtime subsystems.
|
||||||
|
|
||||||
|
## Pitfalls
|
||||||
|
|
||||||
|
- A UI-only kill that removes a task but leaves assets or composer binding alive
|
||||||
|
can still fail later when another Game renders.
|
||||||
|
- A cleanup-only helper without an end-to-end Hub click test can miss the
|
||||||
|
interaction between hitbox, foreground ownership, render owner, and no-resume.
|
||||||
|
- Hard-coded click coordinates in tests make the UI contract harder to maintain;
|
||||||
|
expose the layout hitbox when tests need to exercise it.
|
||||||
|
|
||||||
|
## Takeaways
|
||||||
|
|
||||||
|
- Visible system controls should produce system actions, not direct subsystem
|
||||||
|
mutation from UI code.
|
||||||
|
- Manual kill and Game replacement are variants of the same resident Game
|
||||||
|
termination contract.
|
||||||
|
- Cleanup tests should prove both logical state removal and visible-frame
|
||||||
|
behavior: the control appears before kill and disappears after kill.
|
||||||
|
- "No resume after kill" is as important as "task closed" because resumability
|
||||||
|
is the user-facing state.
|
||||||
+97
@@ -0,0 +1,97 @@
|
|||||||
|
---
|
||||||
|
id: LSN-0055
|
||||||
|
ticket: runtime-owned-variable-glyph-bank-palette-protocol
|
||||||
|
title: Runtime-Owned Asset Protocols Must Align Payload, Residency, and Lookup
|
||||||
|
created: 2026-07-14
|
||||||
|
tags: [runtime, assets, glyph-bank, palette-serialization, protocol]
|
||||||
|
decision: DEC-0041
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
The runtime changed the `GLYPH/indexed_v1` glyph-bank palette contract from a
|
||||||
|
fixed 64-palette payload and resident table to variable palette serialization
|
||||||
|
and variable resident palette storage.
|
||||||
|
|
||||||
|
The initiating pressure came from packer/studio: fixed RGBA8888 palette padding
|
||||||
|
made small glyph banks pay for `64 * 16 * 4` palette bytes even when they used
|
||||||
|
far fewer palettes. The important architectural point was that the runtime, not
|
||||||
|
the packer, had to decide the protocol. The packer can only emit payloads that
|
||||||
|
conform to the runtime contract once the runtime spec is published.
|
||||||
|
|
||||||
|
## Key Decisions
|
||||||
|
|
||||||
|
### Variable Glyph Bank Palette Protocol
|
||||||
|
|
||||||
|
**What:**
|
||||||
|
`palette_count` became the number of serialized palettes and the number of
|
||||||
|
resident palettes in the loaded `GlyphBank`. The valid range is `1..=64`.
|
||||||
|
`palette_id` remains a direct palette identity and is valid only when
|
||||||
|
`palette_id < palette_count` for the referenced resident bank.
|
||||||
|
|
||||||
|
**Why:**
|
||||||
|
Keeping serialized count variable while retaining a fixed 64-slot resident
|
||||||
|
table would preserve two meanings for palette capacity. The runtime would save
|
||||||
|
payload bytes but still carry a split contract between payload shape, resident
|
||||||
|
shape, and lookup validity. Making all three agree gives the runtime one
|
||||||
|
source of truth.
|
||||||
|
|
||||||
|
**Trade-offs:**
|
||||||
|
Palette validity is now bank-dependent. Scene and sprite composition must check
|
||||||
|
the referenced loaded bank instead of relying on a global `0..63` rule. This
|
||||||
|
adds validation work, but it prevents invalid references from silently becoming
|
||||||
|
transparent or default colors.
|
||||||
|
|
||||||
|
## Patterns and Algorithms
|
||||||
|
|
||||||
|
Let the runtime own runtime-facing asset protocols. Tooling can discover pain,
|
||||||
|
but the runtime spec must define effective metadata, payload shape, resident
|
||||||
|
shape, and failure semantics.
|
||||||
|
|
||||||
|
Make count fields material. A count such as `palette_count` should not describe
|
||||||
|
only what the producer authored or only what the payload happens to include. If
|
||||||
|
runtime lookup depends on it, the count must also define resident state and
|
||||||
|
validation boundaries.
|
||||||
|
|
||||||
|
Keep identity direct unless a real remapping problem exists. Sparse-to-dense
|
||||||
|
palette remapping was rejected because it would add a second identity layer
|
||||||
|
across scenes, sprites, packer output, and runtime lookup. V1 keeps palette id
|
||||||
|
`N` as palette slot `N` in the resident bank.
|
||||||
|
|
||||||
|
Separate transparent color from invalid lookup. RGBA alpha is valid color data.
|
||||||
|
An invalid palette reference must be observable as invalid; it must not be
|
||||||
|
collapsed into `Color::TRANSPARENT`.
|
||||||
|
|
||||||
|
Use residue scans after protocol migrations. Search for fixed byte formulas,
|
||||||
|
old constants, fixture helpers, and spec phrases. Legitimate hits should be
|
||||||
|
renamed as maximum-bound concepts, not left as accidental active contracts.
|
||||||
|
|
||||||
|
## Pitfalls
|
||||||
|
|
||||||
|
Partially variable specs are worse than fixed specs. The asset spec already had
|
||||||
|
variable size formulas in some places but still required `palette_count = 64`
|
||||||
|
elsewhere. That contradiction made it unclear which rule was canonical.
|
||||||
|
|
||||||
|
Resident data structures can preserve obsolete protocol assumptions after the
|
||||||
|
payload changes. A fixed array in `GlyphBank` would have kept the old model
|
||||||
|
alive even if decode accepted variable payloads.
|
||||||
|
|
||||||
|
Fallback rendering hides contract errors. Returning transparent for an invalid
|
||||||
|
palette id makes bad assets and bad scene references look like intentional
|
||||||
|
alpha, which is exactly the wrong failure mode for a runtime protocol.
|
||||||
|
|
||||||
|
Fixture generators are part of the contract surface. Stress cartridges and
|
||||||
|
test payload builders must express whether they are using a variable count or
|
||||||
|
the v1 maximum; otherwise they reintroduce fixed-padding assumptions.
|
||||||
|
|
||||||
|
## Takeaways
|
||||||
|
|
||||||
|
- Runtime-facing asset protocols should align payload size, resident memory,
|
||||||
|
and lookup validity.
|
||||||
|
- `palette_count` is effective runtime metadata, not producer commentary.
|
||||||
|
- Direct identity is simpler than remapping until a concrete remapping need
|
||||||
|
exists.
|
||||||
|
- Invalid palette references should fail explicitly; transparent remains a
|
||||||
|
valid RGBA color, not an error substitute.
|
||||||
|
- Protocol migrations need spec edits, code changes, fixture updates, and
|
||||||
|
residue scans in the same workflow.
|
||||||
+61
@@ -0,0 +1,61 @@
|
|||||||
|
---
|
||||||
|
id: LSN-0056
|
||||||
|
ticket: corrigir-identificacao-formato-pbx
|
||||||
|
title: Runtime Artifact Identity Must Not Borrow Frontend Names
|
||||||
|
created: 2026-07-15
|
||||||
|
tags: [runtime, bytecode, pbx, frontend, format-boundary]
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
Prometeu accepts bytecode produced by multiple frontends. PBS is the base
|
||||||
|
frontend language, while PBX is the executable bytecode artifact consumed by the
|
||||||
|
runtime.
|
||||||
|
|
||||||
|
The runtime had inherited PBS terminology in the executable bytecode path,
|
||||||
|
including the serialized magic number, comments, tests, and VM loader checks.
|
||||||
|
That made one frontend appear to own the runtime executable format.
|
||||||
|
|
||||||
|
## Key Decisions
|
||||||
|
|
||||||
|
### PBX Executable Format Identity
|
||||||
|
|
||||||
|
**What:** PBX is the runtime executable bytecode format, and `PBX\0` is its only
|
||||||
|
valid magic number.
|
||||||
|
|
||||||
|
**Why:** Runtime artifact identity must be independent from any frontend that can
|
||||||
|
produce the artifact. Naming the executable format after PBS would make the
|
||||||
|
runtime boundary look language-specific.
|
||||||
|
|
||||||
|
**Trade-offs:** The correction intentionally rejects old PBS-prefixed executable
|
||||||
|
artifacts instead of carrying a compatibility alias. This keeps the format
|
||||||
|
contract singular, but requires stale generated fixtures to be regenerated or
|
||||||
|
updated.
|
||||||
|
|
||||||
|
## Patterns and Algorithms
|
||||||
|
|
||||||
|
Put file-format identity in the module that serializes and deserializes the
|
||||||
|
format. Loaders and higher-level runtime code should call that boundary instead
|
||||||
|
of duplicating magic-number checks.
|
||||||
|
|
||||||
|
When renaming an artifact identity, update all fixture construction and generator
|
||||||
|
assertions in the same pass as production serialization. Mixed fixture identity
|
||||||
|
usually means tests are asserting historical spelling rather than current
|
||||||
|
contract.
|
||||||
|
|
||||||
|
## Pitfalls
|
||||||
|
|
||||||
|
Do not globally erase frontend names. PBS remains correct when the subject is
|
||||||
|
the PBS language, stdlib, or frontend-facing API. It is wrong only when it names
|
||||||
|
the executable bytecode artifact.
|
||||||
|
|
||||||
|
Do not preserve old magic values just to make a rename feel less disruptive. If
|
||||||
|
there is no compatibility requirement for old artifacts, aliases keep the
|
||||||
|
incorrect model alive.
|
||||||
|
|
||||||
|
## Takeaways
|
||||||
|
|
||||||
|
- Runtime artifact names should describe the runtime contract, not the compiler
|
||||||
|
or frontend that produced the artifact.
|
||||||
|
- Magic numbers are normative format identity, not cosmetic labels.
|
||||||
|
- Loader code should delegate file-format validation to the format owner.
|
||||||
@@ -1,178 +0,0 @@
|
|||||||
---
|
|
||||||
id: AGD-0044
|
|
||||||
ticket: system-os-cartridge-switch-orchestrator
|
|
||||||
title: SystemOS Cartridge Switch Orchestrator
|
|
||||||
status: accepted
|
|
||||||
created: 2026-07-03
|
|
||||||
resolved:
|
|
||||||
decision:
|
|
||||||
tags: [runtime, os, lifecycle, game, cartridge, architecture]
|
|
||||||
---
|
|
||||||
|
|
||||||
## Contexto
|
|
||||||
|
|
||||||
A `AGD-0041` cobre o caso `Game -> Home/Shell -> mesmo Game`: o usuario sai do
|
|
||||||
foreground do jogo, o SO assume a tela, Shell/Hub pode rodar, e depois o mesmo
|
|
||||||
Game e retomado.
|
|
||||||
|
|
||||||
Existe um segundo caso, diferente, que nao deve ser escondido dentro da
|
|
||||||
`AGD-0041`: `Game A -> Home -> Game B`.
|
|
||||||
|
|
||||||
Nesse fluxo, o usuario esta com um Game rodando, aperta Home, volta para o SO e
|
|
||||||
pede para iniciar outro jogo. O SystemOS nao deve simplesmente chamar um loader
|
|
||||||
por cima do estado atual. Ele precisa orquestrar a substituicao do app corrente:
|
|
||||||
fechar ou descartar o Game residente, limpar estado cartridge-scoped, resolver o
|
|
||||||
novo alvo, carregar o proximo cartucho e entrar no novo estado de firmware.
|
|
||||||
|
|
||||||
Essa agenda tambem se relaciona com a `AGD-0003 / system-run-cart`: `run_cart`,
|
|
||||||
se existir, nao e userland e nao e o orquestrador. O carregador de cartucho e
|
|
||||||
apenas uma etapa dentro de uma transicao comandada pelo SystemOS.
|
|
||||||
|
|
||||||
## Problema
|
|
||||||
|
|
||||||
Sem um orquestrador explicito de troca de cartucho no SystemOS, a plataforma
|
|
||||||
pode cair em estados incoerentes:
|
|
||||||
|
|
||||||
- carregar um novo Game sem fechar corretamente o Game anterior;
|
|
||||||
- reaproveitar estado VM, assets, input, audio, render ou telemetria do cartucho
|
|
||||||
anterior;
|
|
||||||
- misturar boot direto por linha de comando com troca de app sob o SO;
|
|
||||||
- deixar o loader decidir lifecycle, quando ele deveria apenas materializar o
|
|
||||||
cartucho alvo;
|
|
||||||
- tentar implementar `Home -> outro Game` antes de existir o contrato de
|
|
||||||
foreground/pausa definido pela `AGD-0041`.
|
|
||||||
|
|
||||||
## Pontos Criticos
|
|
||||||
|
|
||||||
- Esta agenda deve ser executada depois da `AGD-0041`.
|
|
||||||
- `Game -> Home -> mesmo Game` fica fora desta agenda.
|
|
||||||
- O SystemOS deve ser a autoridade da troca entre cartuchos sob o SO.
|
|
||||||
- O loader nao deve possuir politica de fechamento, pausa, foreground ou
|
|
||||||
cleanup.
|
|
||||||
- Boot direto por CLI/debug continua sendo caminho separado e mais simples.
|
|
||||||
- A troca para outro Game deve tratar falha de load sem deixar o sistema em
|
|
||||||
estado parcialmente substituido.
|
|
||||||
- `.pmc`, catalogo completo e UX final de launcher continuam fora de escopo,
|
|
||||||
salvo se forem necessarios para definir o contrato minimo.
|
|
||||||
|
|
||||||
## Opcoes
|
|
||||||
|
|
||||||
### Opcao A - Adiar tudo para depois da AGD-0041
|
|
||||||
|
|
||||||
- **Abordagem:** manter esta agenda como registro de escopo futuro; primeiro
|
|
||||||
fechar e implementar o contrato `Game -> Home -> mesmo Game`.
|
|
||||||
- **Pro:** evita misturar pausa/resume com substituicao de cartucho; reduz risco
|
|
||||||
de reabrir arquitetura durante a `AGD-0041`.
|
|
||||||
- **Contra:** a plataforma continua sem troca `Home -> outro Game` ate uma etapa
|
|
||||||
posterior.
|
|
||||||
- **Manutenibilidade:** alta, porque cada agenda fecha um eixo de lifecycle.
|
|
||||||
|
|
||||||
### Opcao B - Definir agora o contrato conceitual, implementar depois
|
|
||||||
|
|
||||||
- **Abordagem:** fechar uma decisao curta ja dizendo que o orquestrador pertence
|
|
||||||
ao SystemOS, que `run_cart` nao e userland, e que a execucao depende da
|
|
||||||
`AGD-0041`; o plano de codigo fica para depois.
|
|
||||||
- **Pro:** reduz ambiguidade enquanto trabalhamos na `AGD-0041`.
|
|
||||||
- **Contra:** pode produzir uma decisao com pouca evidencia operacional antes
|
|
||||||
do contrato de foreground estar fechado.
|
|
||||||
- **Manutenibilidade:** boa se a decisao for claramente marcada como dependente
|
|
||||||
da `AGD-0041`.
|
|
||||||
|
|
||||||
### Opcao C - Implementar o orquestrador completo agora
|
|
||||||
|
|
||||||
- **Abordagem:** tentar resolver `Game A -> Home -> Game B` antes ou junto da
|
|
||||||
`AGD-0041`.
|
|
||||||
- **Pro:** ataca o fluxo final diretamente.
|
|
||||||
- **Contra:** mistura pausa/resume, fechamento, cleanup, resolucao de alvo e
|
|
||||||
falha de load em uma unica frente; alto risco de contrato instavel.
|
|
||||||
- **Manutenibilidade:** baixa para v1, porque a troca completa depende do
|
|
||||||
contrato de foreground ainda aberto.
|
|
||||||
|
|
||||||
## Sugestao / Recomendacao
|
|
||||||
|
|
||||||
`DSC-0041` foi fechada e o contrato de foreground/pausa/resume ja existe. A
|
|
||||||
recomendacao agora deixa de ser adiar e passa a ser fechar uma decisao curta
|
|
||||||
para o orquestrador de troca `Game A -> Home -> Game B`.
|
|
||||||
|
|
||||||
O contrato sugerido e:
|
|
||||||
|
|
||||||
- trocar para outro Game e uma substituicao controlada, nao uma pausa/resume;
|
|
||||||
- o Game residente anterior e fechado/descartado;
|
|
||||||
- a VM session do Game anterior e removida;
|
|
||||||
- o novo Game sempre recebe uma VM session nova e zerada;
|
|
||||||
- se o novo load falhar, o sistema volta ao Home/Hub com diagnostico e nao
|
|
||||||
tenta preservar o Game anterior em v1;
|
|
||||||
- o loader continua sendo etapa interna, sem possuir politica de lifecycle;
|
|
||||||
- a evidencia minima deve usar dois cartuchos distintos, incluindo um cartucho
|
|
||||||
simplista `dummy-boy` alem do stress test.
|
|
||||||
|
|
||||||
## Perguntas em Aberto
|
|
||||||
|
|
||||||
- [x] Depois da `AGD-0041`, qual estado representa um Game que sera descartado
|
|
||||||
em vez de retomado?
|
|
||||||
- Resposta: fechamento/encerramento controlado, nao `PausedSuspended`. O Game
|
|
||||||
anterior deixa de ser resident/resumable e sua VM session e removida.
|
|
||||||
- [x] O fechamento do Game atual e observavel para o firmware/game, ou e uma
|
|
||||||
destruicao interna do SystemOS?
|
|
||||||
- Resposta: deve ser observavel como uma transicao de lifecycle/firmware, mas
|
|
||||||
nao cooperativo nem bloqueante para o Game. O SystemOS tem autoridade para
|
|
||||||
encerrar e descartar a sessao. Pode ser emitido um evento de encerramento
|
|
||||||
para permitir save/flush cooperativo quando existir esse mecanismo, mas a
|
|
||||||
troca nao deve depender da resposta do Game.
|
|
||||||
- [x] Quais estados cartridge-scoped devem ser limpos antes do novo load: VM,
|
|
||||||
assets, FS handles, input, audio, render ownership, telemetry, logs?
|
|
||||||
- Resposta: a troca nao reaproveita VM. O Game anterior e encerrado, sua VM
|
|
||||||
session e descartada, e o novo Game recebe VM/session nova e zerada. Devem
|
|
||||||
ser limpos ou reatribuídos os estados cartridge-scoped ligados a VM,
|
|
||||||
handles abertos, input pendente/barreiras, audio do app, render ownership,
|
|
||||||
telemetry/debug/crash state do app. Logs historicos podem permanecer como
|
|
||||||
observabilidade.
|
|
||||||
- [x] Se o novo cartucho falha ao carregar, o sistema volta ao Home, mostra uma
|
|
||||||
tela de erro, ou tenta preservar o Game anterior?
|
|
||||||
- Resposta: o Game anterior ja foi encerrado. Se o novo load falha, a sessao
|
|
||||||
parcial do novo Game e descartada e o sistema volta ao Home/Hub com
|
|
||||||
diagnostico. Preservar o Game anterior fica fora de escopo em v1.
|
|
||||||
- [x] Como a resolucao do novo alvo e representada sem depender de catalogo
|
|
||||||
completo ou `.pmc`?
|
|
||||||
- Resposta: para o contrato minimo, o alvo pode ser um path/entrada ja
|
|
||||||
resolvido pelo Hub/game library atual. O contrato nao depende de `.pmc` nem
|
|
||||||
de catalogo final.
|
|
||||||
- [x] Qual evidencia minima prova `Game A -> Home -> Game B` sem depender de UX
|
|
||||||
final de launcher?
|
|
||||||
- Resposta: criar um cartucho `dummy-boy` ao lado do stress test. O teste deve
|
|
||||||
provar `Stress -> Home -> Dummy Boy`, com troca de VM session, identidade de
|
|
||||||
cartridge distinta e render observavel do novo Game.
|
|
||||||
|
|
||||||
## Criterio para Encerrar
|
|
||||||
|
|
||||||
A agenda pode virar decisao quando:
|
|
||||||
|
|
||||||
- a `AGD-0041` tiver fechado o contrato de foreground/pausa/resume;
|
|
||||||
- estiver claro que o orquestrador pertence ao SystemOS;
|
|
||||||
- `run_cart`/loader estiver limitado a etapa interna, nao userland;
|
|
||||||
- existir regra para fechar/descartar o Game atual;
|
|
||||||
- existir contrato de limpeza de estado cartridge-scoped;
|
|
||||||
- existir politica para falha de carregamento do novo Game;
|
|
||||||
- houver criterio de teste minimo para `Game A -> Home -> Game B`.
|
|
||||||
|
|
||||||
## Discussao
|
|
||||||
|
|
||||||
- 2026-07-03: Agenda criada a partir da separacao entre `AGD-0041`
|
|
||||||
(`Game -> Home -> mesmo Game`) e `AGD-0003` (`run_cart`/loader nao userland).
|
|
||||||
O novo escopo cobre a troca posterior `Game A -> Home -> Game B`, com
|
|
||||||
orquestracao pelo SystemOS depois que o contrato de foreground estiver
|
|
||||||
fechado.
|
|
||||||
- 2026-07-05: Apos fechamento de `DSC-0041`, a discussao convergiu para troca
|
|
||||||
destrutiva simples em v1: ao iniciar outro Game, o Game residente anterior e
|
|
||||||
encerrado, sua VM session e removida, e o novo Game recebe VM session nova.
|
|
||||||
Falha de load volta ao Home/Hub com diagnostico. A evidencia minima deve
|
|
||||||
incluir um novo cartucho `dummy-boy` que desenha um quadrado com cores
|
|
||||||
oscilando, alem do stress test.
|
|
||||||
- 2026-07-05: Refinamento: o encerramento do Game anterior pode emitir evento
|
|
||||||
cooperativo para save/flush, mas esse evento nao e uma permissao nem uma
|
|
||||||
barreira obrigatoria. O SystemOS continua com autoridade para concluir a troca
|
|
||||||
e remover a VM session anterior.
|
|
||||||
|
|
||||||
## Resolution
|
|
||||||
|
|
||||||
Pronta para virar decisao, pendente confirmacao explicita do usuario.
|
|
||||||
@@ -0,0 +1,208 @@
|
|||||||
|
---
|
||||||
|
id: AGD-0048
|
||||||
|
ticket: background-service-audio-execution
|
||||||
|
title: Agenda - Background Service and Audio Execution
|
||||||
|
status: open
|
||||||
|
created: 2026-07-05
|
||||||
|
resolved:
|
||||||
|
decision:
|
||||||
|
tags: [runtime, os, lifecycle, service, audio, background, architecture]
|
||||||
|
---
|
||||||
|
|
||||||
|
# Agenda - Background Service and Audio Execution
|
||||||
|
|
||||||
|
## Contexto
|
||||||
|
|
||||||
|
O runtime ja tem sinais claros de preparacao para multitarefa controlada:
|
||||||
|
|
||||||
|
- `TaskState::Background` existe como estado de tarefa;
|
||||||
|
- `VmSession` separa estado mutavel de VM por tarefa/processo;
|
||||||
|
- `SystemOS` e dono de lifecycle, task/process, VM sessions, filesystem,
|
||||||
|
memcard, windows e logging;
|
||||||
|
- a spec de eventos separa foreground ownership de execution eligibility;
|
||||||
|
- o contrato atual declara que execucao real em background fica fora do v1, mas
|
||||||
|
o modelo foi desenhado para permitir servicos ou processos de midia no futuro.
|
||||||
|
|
||||||
|
O caso motivador e:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Game foreground -> Home -> music player -> escolher musica -> voltar ao Game
|
||||||
|
```
|
||||||
|
|
||||||
|
Depois disso, o Game deve voltar ao foreground enquanto o player continua
|
||||||
|
executando e produzindo audio junto com audio do Game.
|
||||||
|
|
||||||
|
## Problema
|
||||||
|
|
||||||
|
Hoje o runtime preserva sessoes, mas nao tem contrato para uma sessao continuar
|
||||||
|
executando quando nao e foreground.
|
||||||
|
|
||||||
|
Os pontos atuais que bloqueiam o caso:
|
||||||
|
|
||||||
|
- `TaskKind` so distingue `Game` e `Shell`;
|
||||||
|
- `ProcessKind` so distingue `VmGame`, `VmShell` e `NativeShell`;
|
||||||
|
- `ProcessState` nao possui estado normativo de background-running;
|
||||||
|
- `GameRunningStep` ticka apenas o Game foreground;
|
||||||
|
- `ShellRunningStep` ticka apenas o Shell foreground;
|
||||||
|
- `HubHomeStep` nao ticka sessoes VM em background;
|
||||||
|
- `Audio` e `AudioMixer` usam vozes globais sem namespace por tarefa/sessao;
|
||||||
|
- cada logical frame chama `platform.audio_mut().clear_commands()`, o que torna
|
||||||
|
perigoso tickar dois produtores de audio no mesmo frame;
|
||||||
|
- pausa de lifecycle hoje emite `MasterPause`, afetando o mixer inteiro.
|
||||||
|
|
||||||
|
Sem uma decisao, background service pode virar apenas "tickar mais uma VM", mas
|
||||||
|
isso quebraria isolamento, audio, debugger, lifecycle e previsibilidade.
|
||||||
|
|
||||||
|
## Pontos Criticos
|
||||||
|
|
||||||
|
1. **Execution eligibility nao e foreground.**
|
||||||
|
O contrato atual ja separa os conceitos, mas a implementacao ainda so ticka o
|
||||||
|
owner foreground. Precisamos introduzir uma politica explicita de quem pode
|
||||||
|
executar em background.
|
||||||
|
|
||||||
|
2. **Servico nao e Shell escondido.**
|
||||||
|
Um music player pode ter UI de Shell para escolher musica, mas a reproducao
|
||||||
|
continua como servico quando a UI deixa o foreground. Fechar isso como
|
||||||
|
`Shell` em background confundiria janela, tarefa, sessao e servico.
|
||||||
|
|
||||||
|
3. **Audio precisa de origem.**
|
||||||
|
Hoje `voice_id` e global no mixer. Se Game e player usam `voice_id = 0`, um
|
||||||
|
sobrescreve o outro. Precisamos decidir se o mixer tera namespaces por
|
||||||
|
`AudioOwner`, se servicos terao pool dedicado, ou se o player nao usara a
|
||||||
|
mesma superficie `audio.*`.
|
||||||
|
|
||||||
|
4. **Pausa de Game nao pode pausar servico de midia.**
|
||||||
|
`MasterPause` global serve para o contrato atual de pausa/debug, mas nao
|
||||||
|
expressa "pausar Game audio e manter music player". Pausa precisa virar
|
||||||
|
escopo por origem ou politica de mixer.
|
||||||
|
|
||||||
|
5. **Servico precisa de lifecycle proprio.**
|
||||||
|
Deve existir contrato para start, foreground UI, background-running, stop,
|
||||||
|
crash, terminate, recurso negado, e talvez wake/resume de UI.
|
||||||
|
|
||||||
|
6. **Budget e determinismo precisam ser fechados.**
|
||||||
|
Se servicos rodam junto com Game, precisamos decidir cota por frame, ordem de
|
||||||
|
ticks, starvation, crash isolation, e se background service participa do
|
||||||
|
mesmo tempo deterministico da maquina.
|
||||||
|
|
||||||
|
7. **Sistema de apps precisa descobrir e lancar o player.**
|
||||||
|
Hoje Home lista Game cartridges e tem Shells nativos fixos. O caso de music
|
||||||
|
player exige decidir se ele e cartridge `System`, app instalado, Shell nativo,
|
||||||
|
ou novo perfil `Service`.
|
||||||
|
|
||||||
|
## Opcoes
|
||||||
|
|
||||||
|
### Opcao A - Background Service como novo tipo de processo/sessao
|
||||||
|
|
||||||
|
Criar contrato explicito para `Service`:
|
||||||
|
|
||||||
|
- `TaskKind::Service` ou entidade equivalente;
|
||||||
|
- `ProcessKind::VmService` / `NativeService`;
|
||||||
|
- execution eligibility independente de foreground;
|
||||||
|
- UI de controle opcional via Shell task associada ao servico;
|
||||||
|
- audio com origem por service/session;
|
||||||
|
- lifecycle proprio: start, background, foreground-control, stop, crash.
|
||||||
|
|
||||||
|
**Pros:**
|
||||||
|
- modela diretamente music player e futuros servicos;
|
||||||
|
- preserva a separacao entre UI foreground e execucao;
|
||||||
|
- evita transformar Shell em "processo que tambem e daemon";
|
||||||
|
- facilita quotas, permissao e observabilidade.
|
||||||
|
|
||||||
|
**Contras:**
|
||||||
|
- maior mudanca arquitetural;
|
||||||
|
- exige novo contrato em specs, SystemOS, firmware, audio e testes;
|
||||||
|
- precisa fechar politica de recursos antes de implementar.
|
||||||
|
|
||||||
|
**Manutencao:**
|
||||||
|
- melhor base para crescer com qualidade, desde que o MVP seja pequeno.
|
||||||
|
|
||||||
|
### Opcao B - Shell em background com audio permitido
|
||||||
|
|
||||||
|
Permitir que uma VM Shell continue tickando quando sai do foreground e use audio
|
||||||
|
normalmente.
|
||||||
|
|
||||||
|
**Pros:**
|
||||||
|
- reaproveita Shell, WindowManager e VM session existentes;
|
||||||
|
- menor numero de novos tipos no curto prazo.
|
||||||
|
|
||||||
|
**Contras:**
|
||||||
|
- mistura UI e servico;
|
||||||
|
- torna `TaskState::Background` semantico antes de definir `ProcessState`;
|
||||||
|
- abre precedente para qualquer Shell continuar executando;
|
||||||
|
- nao resolve sozinho namespace de audio, pause por origem, quotas e debugging.
|
||||||
|
|
||||||
|
**Manutencao:**
|
||||||
|
- atraente como atalho, mas tende a espalhar excecoes pela firmware state
|
||||||
|
machine.
|
||||||
|
|
||||||
|
### Opcao C - Audio player como servico nativo OS-owned, sem VM background
|
||||||
|
|
||||||
|
Implementar music player como servico nativo de SystemOS, controlado por uma
|
||||||
|
Shell UI. A reproducao continua no host/OS sem tickar VM em background.
|
||||||
|
|
||||||
|
**Pros:**
|
||||||
|
- entrega o caso de musica com menor risco para scheduler VM;
|
||||||
|
- evita abrir execucao arbitraria de background agora;
|
||||||
|
- audio service pode ser projetado como recurso OS-owned e depois exposto.
|
||||||
|
|
||||||
|
**Contras:**
|
||||||
|
- nao resolve background VM services em geral;
|
||||||
|
- player deixa de ser app userland completo no primeiro ciclo;
|
||||||
|
- precisa ainda fechar origem/mixagem de audio e relacao com UI.
|
||||||
|
|
||||||
|
**Manutencao:**
|
||||||
|
- bom MVP se o objetivo imediato for media playback, mas deve ser declarado como
|
||||||
|
`media service` nativo, nao como contrato geral de background VM.
|
||||||
|
|
||||||
|
## Sugestao / Recomendacao
|
||||||
|
|
||||||
|
Recomendo fechar em duas camadas:
|
||||||
|
|
||||||
|
1. **Decisao de arquitetura:** introduzir o conceito de service/background
|
||||||
|
execution como contrato de SystemOS, separado de foreground Shell e Game.
|
||||||
|
Essa decisao deve definir execution eligibility, lifecycle, quotas, crash
|
||||||
|
policy, controle de UI e relacao com VM sessions.
|
||||||
|
|
||||||
|
2. **MVP de media:** implementar primeiro um `media/audio service` com escopo
|
||||||
|
reduzido, preferencialmente OS-owned ou `Service` bem delimitado, antes de
|
||||||
|
permitir background VM arbitrario.
|
||||||
|
|
||||||
|
Para excelente qualidade, o primeiro plano nao deve tentar "qualquer app em
|
||||||
|
background". O alvo deve ser: um unico servico de audio/midia, com origem de
|
||||||
|
audio propria, controle por Hub/Shell, execucao enquanto Game esta foreground,
|
||||||
|
e testes end-to-end de mistura e lifecycle.
|
||||||
|
|
||||||
|
## Perguntas em Aberto
|
||||||
|
|
||||||
|
- O music player deve ser um cartridge `System`, um novo `Service`, ou um
|
||||||
|
servico nativo do OS controlado por Shell?
|
||||||
|
- A UI do player e a reproducao pertencem a mesma tarefa ou a tarefas
|
||||||
|
separadas?
|
||||||
|
- Um servico pode ter janela foreground temporaria e continuar sem janela?
|
||||||
|
- Quantos servicos background podem existir no MVP: um media service ou N
|
||||||
|
servicos?
|
||||||
|
- O background service recebe ticks todo frame, tick rate reduzido, ou apenas
|
||||||
|
eventos?
|
||||||
|
- O audio mixer deve isolar vozes por `TaskId`, `ProcessId`, `VmSessionId`,
|
||||||
|
`AppId`, ou novo `AudioOwner`?
|
||||||
|
- Como pausar apenas o audio do Game durante Home/debug sem pausar musica?
|
||||||
|
- O debugger inspeciona foreground session apenas ou tambem sessoes background?
|
||||||
|
- Como crash de servico e exibido: toast/log, janela de crash, ou parada
|
||||||
|
silenciosa com diagnostico?
|
||||||
|
- Que capacidades sao necessarias para media service: `audio`, `fs`, `asset`,
|
||||||
|
talvez `background_audio`?
|
||||||
|
|
||||||
|
## Criterio para Encerrar
|
||||||
|
|
||||||
|
Esta agenda pode virar decisao quando houver resposta escrita para:
|
||||||
|
|
||||||
|
- modelo de entidade (`Service` novo vs Shell background vs native OS service);
|
||||||
|
- execution eligibility e ordem de ticks;
|
||||||
|
- lifecycle e estados de task/process;
|
||||||
|
- ownership/namespace de audio e politica de pausa por origem;
|
||||||
|
- relacao entre UI foreground do player e reproducao background;
|
||||||
|
- escopo do MVP e explicitamente o que fica fora;
|
||||||
|
- testes obrigatorios de lifecycle, audio mixing, crash isolation e regressao do
|
||||||
|
contrato Game/Home/Shell existente.
|
||||||
|
|
||||||
@@ -0,0 +1,138 @@
|
|||||||
|
---
|
||||||
|
id: AGD-0050
|
||||||
|
ticket: portable-host-backend-strategy
|
||||||
|
title: Portable Host Backend Strategy
|
||||||
|
status: open
|
||||||
|
created: 2026-07-14
|
||||||
|
resolved:
|
||||||
|
decision:
|
||||||
|
tags: [host, desktop, portable, sdl, backend, rendering, input, audio, linux, android, handheld]
|
||||||
|
---
|
||||||
|
|
||||||
|
## Contexto
|
||||||
|
|
||||||
|
O runtime ja tem uma fronteira de host relativamente clara: o host desktop atual vive em `crates/host/prometeu-host-desktop-winit`, usando `winit`, `pixels` e `cpal` para janela, apresentacao de framebuffer, input e audio.
|
||||||
|
|
||||||
|
A direcao desejada nao e substituir esse host de forma disruptiva no primeiro corte. A proposta e estudar e construir um segundo host portatil para servir como runtime host em handhelds e consoles portateis, especialmente hardwares chineses que rodam Linux internamente e, em alguns casos, Android customizado. O mesmo host tambem deve servir como base para uma futura versao DIY do hardware, desde que ela rode sobre um Linux base compatível. SDL e a hipotese principal, mas a agenda tambem deve avaliar outras familias de host/backend antes de virar decisao normativa.
|
||||||
|
|
||||||
|
Esse novo host deve conviver com o host atual durante estabilizacao, mas nao e descartavel: ele e candidato a se tornar o host principal quando provar paridade e estabilidade.
|
||||||
|
|
||||||
|
A troca deve ficar isolada no dominio de host: contratos de runtime, firmware, frame, input semantico e audio semantico nao devem mudar por causa da escolha de backend. Essa separacao e justamente o objetivo arquitetural que permite que um host portatil evolua para principal sem arrastar o runtime.
|
||||||
|
|
||||||
|
## Problema
|
||||||
|
|
||||||
|
Hoje a existencia de um unico host desktop torna dificil separar problemas do runtime de problemas do adaptador de plataforma. Um novo host portatil pode ajudar em testes, portabilidade, comparacao operacional e reducao de dependencia de uma pilha unica de janela/render/audio. O alvo "mobile" desta agenda nao significa telefone/tablet como produto primario; significa hardware portatil dedicado, geralmente com controles fisicos, framebuffer/display integrado, Linux customizado e distribuicao fora do modelo desktop tradicional. O alvo tambem inclui um possivel handheld DIY futuro, em que o valor esperado e ja existir um host pronto se o dispositivo expuser um Linux base suficiente.
|
||||||
|
|
||||||
|
O risco e tratar uma tecnologia especifica como resposta antes de comparar os requisitos reais de Linux handheld e Android. A agenda precisa cravar o modelo de host paralelo em estabilizacao, com destino de host principal, e entao escolher a familia de backend que melhor atende esse objetivo.
|
||||||
|
|
||||||
|
## Pontos Criticos
|
||||||
|
|
||||||
|
- A troca de host deve ser simples e local ao host, sem exigir mudancas em runtime, firmware, asset protocol, render packet, VM ou syscalls.
|
||||||
|
- O novo host precisa consumir as mesmas saidas canonicas do runtime: frames RGBA8888, comandos semanticos de audio e eventos de input normalizados.
|
||||||
|
- A estrategia deve preservar o host `winit` enquanto o novo host ainda nao provar equivalencia operacional, mas o novo host e candidato a virar o host principal depois dessa prova.
|
||||||
|
- O alvo primario e portabilidade operacional para handhelds Linux e consoles portateis com controles fisicos; Android customizado e um alvo possivel que deve influenciar a escolha de API, packaging e input/audio.
|
||||||
|
- O host portatil deve ser viavel em um futuro hardware DIY rodando Linux base, sem exigir um runtime especial ou fork de contratos.
|
||||||
|
- Testes devem distinguir contrato comum de host de detalhes especificos de backend.
|
||||||
|
- SDL2 pode ter ecossistema Rust mais estabelecido; SDL3 pode estar mais alinhado com a direcao upstream. A escolha da versao e uma pergunta separada da decisao de criar um segundo host.
|
||||||
|
- A arquitetura deve evitar duplicar logica de runtime loop, pacing, debugger, stats e presentation policy quando essa logica for comum a qualquer host.
|
||||||
|
- Outras familias de host tambem devem ser avaliadas: evoluir `winit`, SDL2/SDL3, backend Android nativo, ou uma camada multiplataforma alternativa.
|
||||||
|
|
||||||
|
## Opcoes
|
||||||
|
|
||||||
|
### Opcao A - Manter apenas o host winit atual
|
||||||
|
|
||||||
|
- **Abordagem:** continuar evoluindo `prometeu-host-desktop-winit` como unico host desktop.
|
||||||
|
- **Pro:** menor custo imediato; evita nova dependencia nativa.
|
||||||
|
- **Con:** mantem a pilha de plataforma unica como ponto de acoplamento pratico.
|
||||||
|
- **Tradeoff:** bom para estabilidade curta, fraco para provar independencia real do host.
|
||||||
|
|
||||||
|
### Opcao B - Migrar diretamente do host winit para outro backend
|
||||||
|
|
||||||
|
- **Abordagem:** substituir o host desktop atual por um novo backend portatil assim que a escolha tecnologica for feita.
|
||||||
|
- **Pro:** reduz a manutencao para um unico host depois da migracao.
|
||||||
|
- **Con:** aumenta risco de regressao e mistura decisao de backend com mudanca operacional.
|
||||||
|
- **Tradeoff:** so faz sentido depois de prova local de superioridade e paridade, o que ainda nao existe.
|
||||||
|
|
||||||
|
### Opcao C - Criar um host SDL paralelo com destino de principal
|
||||||
|
|
||||||
|
- **Abordagem:** adicionar um novo crate/binario de host SDL que implemente os mesmos contratos externos do host atual, mantendo `winit` como referencia e rollback ate haver evidencia de equivalencia.
|
||||||
|
- **Pro:** permite teste A/B, reduz risco, valida se a fronteira de host esta realmente limpa, atende a meta de handheld Linux/Android customizado/DIY e preserva caminho para tornar SDL o host principal.
|
||||||
|
- **Con:** aumenta temporariamente manutencao e exige fatorar partes comuns se houver duplicacao.
|
||||||
|
- **Tradeoff:** melhor caminho para chegar a um host principal portatil sem reabrir runtime.
|
||||||
|
|
||||||
|
### Opcao D - Evoluir winit/pixels/cpal como host portatil
|
||||||
|
|
||||||
|
- **Abordagem:** manter a familia atual e investir em configuracao, input, fullscreen, packaging e compatibilidade de Linux handheld/Android/DIY dentro dela.
|
||||||
|
- **Pro:** reaproveita o host existente e reduz dependencias nativas novas.
|
||||||
|
- **Con:** pode nao resolver os problemas praticos de distribuicao, gamepad/device handling, fullscreen/scaling, Android customizado e ambientes handheld.
|
||||||
|
- **Tradeoff:** forte se a pilha atual suportar bem os alvos; fraco se o problema real for portabilidade operacional.
|
||||||
|
|
||||||
|
### Opcao E - Host Android nativo separado
|
||||||
|
|
||||||
|
- **Abordagem:** tratar Linux handheld e Android como hosts diferentes: SDL ou winit para Linux; Android com camada nativa/propria quando o alvo amadurecer.
|
||||||
|
- **Pro:** permite respeitar o ciclo de vida, packaging, input e audio do Android sem contaminar o host Linux.
|
||||||
|
- **Con:** duplica mais superficie e adia a promessa de um host portatil unico.
|
||||||
|
- **Tradeoff:** bom se Android tiver requisitos proprios demais; ruim se SDL conseguir cobrir Android bem o bastante.
|
||||||
|
|
||||||
|
### Opcao F - Camada multiplataforma alternativa
|
||||||
|
|
||||||
|
- **Abordagem:** avaliar alternativas como uma camada Rust-first ou game-framework-level para janela, input, audio e render.
|
||||||
|
- **Pro:** pode reduzir FFI nativa e integrar melhor com Cargo.
|
||||||
|
- **Con:** pode ser menos madura para Linux handheld/Android real, packaging e controles.
|
||||||
|
- **Tradeoff:** deve ser considerada, mas precisa provar vantagem concreta sobre SDL para justificar risco.
|
||||||
|
|
||||||
|
## Sugestao / Recomendacao
|
||||||
|
|
||||||
|
Recomendacao inicial: manter a **Opcao C** como favorita, mas ampliar a fase de agenda para comparar SDL com as demais familias de host antes da decisao. O resultado desejado continua sendo um segundo host portatil, inicialmente paralelo, com destino explicito de se tornar o host principal quando atingir paridade e estabilidade.
|
||||||
|
|
||||||
|
O caminho recomendado e:
|
||||||
|
|
||||||
|
1. Definir o contrato minimo de equivalencia entre hosts: janela, framebuffer RGBA8888, input, audio, pacing, debugger/logs e encerramento.
|
||||||
|
2. Identificar o que e comum ao host e o que e backend especifico.
|
||||||
|
3. Comparar as familias candidatas contra esse contrato: SDL2, SDL3, winit atual evoluido, Android nativo separado e alternativas Rust-first.
|
||||||
|
4. Implementar o candidato escolhido como novo crate/binario sem remover `prometeu-host-desktop-winit`.
|
||||||
|
5. Permitir troca simples por binario/comando/feature, mantendo o runtime cego para a escolha.
|
||||||
|
6. Tratar handheld Linux como alvo primario de produto para esse host; tratar Android customizado e DIY Linux como restricoes de desenho quando afetarem backend, packaging, input, audio ou boot/runtime integration.
|
||||||
|
7. Promover o novo host a principal apenas depois de evidencia de estabilidade e paridade.
|
||||||
|
|
||||||
|
## Perguntas em Aberto
|
||||||
|
|
||||||
|
- [ ] A primeira implementacao SDL deve usar SDL2 ou SDL3?
|
||||||
|
- [ ] SDL deve ser a familia escolhida, ou winit evoluido, Android nativo separado ou outra camada oferece melhor caminho?
|
||||||
|
- [ ] A selecao do host deve ser por binario separado, feature Cargo, parametro CLI, ou combinacao desses mecanismos?
|
||||||
|
- [ ] Qual e o menor conjunto de comportamento que define paridade aceitavel com o host winit?
|
||||||
|
- [ ] Quais partes do host atual devem virar modulo comum antes do SDL, e quais devem ser duplicadas primeiro para evitar abstracao prematura?
|
||||||
|
- [ ] O host SDL deve reutilizar `cpal` para audio inicialmente ou usar audio SDL desde o primeiro corte?
|
||||||
|
- [ ] Quais familias de hardware handheld Linux devem ser usadas como referencia inicial?
|
||||||
|
- [ ] Handheld Linux exige controles/gamepad, fullscreen, scaling, latency, sleep/resume, framebuffer/display mode ou packaging especificos desde o primeiro corte?
|
||||||
|
- [ ] Qual e o "Linux base" minimo que um futuro hardware DIY precisaria expor para rodar o host portatil sem fork?
|
||||||
|
- [ ] Android customizado deve ser criterio de escolha entre SDL2 e SDL3 agora, ou deve ficar como compatibilidade futura?
|
||||||
|
- [ ] Como validar input e pacing de forma automatizada sem depender de janela real em CI?
|
||||||
|
- [ ] O nome do crate deve ser `prometeu-host-desktop-sdl`, `prometeu-host-desktop-sdl2`, ou algo neutro a versao?
|
||||||
|
|
||||||
|
## Criterio para Encerrar
|
||||||
|
|
||||||
|
A agenda pode virar decision quando estiver claro:
|
||||||
|
|
||||||
|
- se o novo host sera paralelo em estabilizacao, com destino de host principal;
|
||||||
|
- qual familia de backend sera alvo inicial;
|
||||||
|
- se SDL for escolhido, qual versao SDL sera alvo inicial;
|
||||||
|
- como a selecao/troca de host deve funcionar;
|
||||||
|
- quais contratos sao comuns e proibidos de mudar;
|
||||||
|
- quais requisitos minimos de handheld Linux e possivel Android customizado entram no primeiro plano;
|
||||||
|
- qual contrato minimo de Linux base mantem aberta a opcao de hardware DIY;
|
||||||
|
- qual evidencia minima prova paridade suficiente para iniciar planos de implementacao.
|
||||||
|
|
||||||
|
## Discussion
|
||||||
|
|
||||||
|
Ponto inicial aceito pelo usuario: a intencao e ter um segundo host para testes, com troca simples e facil, aproveitando o trabalho ja feito para isolar essa troca no host sem envolver runtime ou outros dominios.
|
||||||
|
|
||||||
|
Atualizacao de escopo: o novo host nao e descartavel. O objetivo e servir como runtime host para sistemas Linux rodando em consoles portateis e hardwares handheld chineses, e possivelmente Android customizado. Assim que estiver estavel, ele deve poder virar o host principal.
|
||||||
|
|
||||||
|
Atualizacao de escopo: outras familias de host/backend tambem devem viver nesta agenda. SDL segue como hipotese forte, mas a decisao deve comparar opcoes antes de cravar a tecnologia.
|
||||||
|
|
||||||
|
Clarificacao: "mobile" nesta agenda nao se refere primariamente a telefone/tablet. O foco sao dispositivos portateis dedicados com Linux interno ou Android customizado, geralmente com controles fisicos e ambiente de distribuicao proprio.
|
||||||
|
|
||||||
|
Clarificacao: a agenda tambem deve preservar a opcao de um futuro hardware DIY. A premissa desejada e que, se esse hardware expuser um Linux base suficiente, o runtime ja tenha um host portatil pronto para rodar nele.
|
||||||
|
|
||||||
|
## Resolution
|
||||||
-174
@@ -1,174 +0,0 @@
|
|||||||
---
|
|
||||||
id: DEC-0039
|
|
||||||
ticket: system-os-cartridge-switch-orchestrator
|
|
||||||
title: SystemOS Game Cartridge Switch Orchestrator
|
|
||||||
status: accepted
|
|
||||||
created: 2026-07-05
|
|
||||||
ref_agenda: AGD-0044
|
|
||||||
tags: [runtime, os, lifecycle, game, cartridge, architecture]
|
|
||||||
---
|
|
||||||
|
|
||||||
## Status
|
|
||||||
|
|
||||||
Open for review.
|
|
||||||
|
|
||||||
## Contexto
|
|
||||||
|
|
||||||
`DEC-0037` fechou o contrato `Game -> Home/Shell -> mesmo Game`: o Game pode
|
|
||||||
ficar residente, ser pausado/suspenso pelo SystemOS, e depois ser retomado.
|
|
||||||
|
|
||||||
`DEC-0038` fechou o ownership de VM sessions: VM-backed mutable execution state
|
|
||||||
pertence a sessoes de VM associadas a processos/tarefas, nao a uma VM global do
|
|
||||||
firmware.
|
|
||||||
|
|
||||||
Esta decision cobre outro fluxo: `Game A -> Home -> Game B`. Nesse caso, o
|
|
||||||
usuario nao esta retomando o mesmo Game. O usuario esta escolhendo substituir o
|
|
||||||
Game residente por outro cartucho. Essa substituicao precisa ser orquestrada
|
|
||||||
pelo SystemOS, nao pelo loader e nao por userland.
|
|
||||||
|
|
||||||
## Decisao
|
|
||||||
|
|
||||||
PROMETEU MUST tratar `Game A -> Home -> Game B` como uma substituicao
|
|
||||||
controlada de Game, nao como pause/resume.
|
|
||||||
|
|
||||||
Quando o usuario escolher iniciar um Game diferente enquanto ja existe um Game
|
|
||||||
residente, SystemOS MUST encerrar o Game residente anterior, remover sua
|
|
||||||
resident state e descartar sua VM session antes de ativar o novo Game como
|
|
||||||
resident/foreground.
|
|
||||||
|
|
||||||
O Game anterior MAY receber um evento cooperativo de encerramento para permitir
|
|
||||||
save/flush quando esse mecanismo existir. Esse evento MUST NOT ser uma
|
|
||||||
permissao, veto ou barreira obrigatoria para a troca. SystemOS MUST manter
|
|
||||||
autoridade para concluir a troca e remover a VM session anterior mesmo se o
|
|
||||||
Game nao reagir.
|
|
||||||
|
|
||||||
O novo Game MUST receber uma VM session nova e zerada. A troca MUST NOT
|
|
||||||
reutilizar a VM session, PC, stack, heap, globals, open handles, cartridge
|
|
||||||
identity, lifecycle state, debug state ou runtime state do Game anterior.
|
|
||||||
|
|
||||||
O loader/materializador de cartridge MUST permanecer uma etapa interna de
|
|
||||||
carregamento. Ele MUST NOT possuir politica de lifecycle, foreground,
|
|
||||||
close/discard, cleanup ou recuperacao de falha.
|
|
||||||
|
|
||||||
Se o novo cartucho falhar ao carregar, SystemOS MUST descartar qualquer session
|
|
||||||
parcial ou estado cartridge-scoped parcial do novo Game e retornar ao Home/Hub
|
|
||||||
com diagnostico. V1 MUST NOT tentar preservar ou restaurar o Game anterior
|
|
||||||
depois que a troca tiver comecado.
|
|
||||||
|
|
||||||
Boot direto por CLI/debug permanece um caminho separado e mais simples. Esta
|
|
||||||
decision governa troca de Game sob SystemOS depois que o usuario retorna ao
|
|
||||||
Home/Hub.
|
|
||||||
|
|
||||||
A evidencia minima de implementacao MUST incluir dois test cartridges
|
|
||||||
distintos: o stress cartridge existente e um novo cartridge `dummy-boy`.
|
|
||||||
`dummy-boy` MUST renderizar um quadrado visualmente distinto com cor oscilante
|
|
||||||
para que os testes provem que o segundo Game, e nao um frame/session anterior
|
|
||||||
stale, esta ativo.
|
|
||||||
|
|
||||||
## Rationale
|
|
||||||
|
|
||||||
Trying to preserve Game A while loading Game B would turn the switch into a
|
|
||||||
transactional snapshot/rollback problem. That is not needed for v1 and would
|
|
||||||
pull in VM snapshot correctness, open handle restoration, assets, render
|
|
||||||
ownership rollback, audio rollback, input state, debugger state, and telemetry
|
|
||||||
rollback.
|
|
||||||
|
|
||||||
The simpler and safer v1 contract is destructive replacement:
|
|
||||||
|
|
||||||
1. the user requests another Game;
|
|
||||||
2. SystemOS ends the previous resident Game;
|
|
||||||
3. SystemOS removes its VM session and cartridge-scoped runtime state;
|
|
||||||
4. SystemOS attempts to load the new Game into a fresh VM session;
|
|
||||||
5. success enters the new Game;
|
|
||||||
6. failure returns to Home/Hub with diagnostic.
|
|
||||||
|
|
||||||
This aligns with `DEC-0037` because pause/suspend remains the same-Game resume
|
|
||||||
flow. It aligns with `DEC-0038` because VM identity is session-owned and each
|
|
||||||
Game receives a distinct VM session.
|
|
||||||
|
|
||||||
## Invariantes / Contrato
|
|
||||||
|
|
||||||
- SystemOS is the authority for switching from one Game cartridge to another
|
|
||||||
under Home/Hub.
|
|
||||||
- `Game -> Home -> same Game` is pause/resume and remains governed by
|
|
||||||
`DEC-0037`.
|
|
||||||
- `Game A -> Home -> Game B` is destructive replacement and is governed by this
|
|
||||||
decision.
|
|
||||||
- A Game that is being replaced MUST stop being resident/resumable.
|
|
||||||
- The previous Game VM session MUST be removed before the new Game becomes the
|
|
||||||
active resident/foreground Game.
|
|
||||||
- A cooperative close/terminate/save event MAY be delivered to the previous
|
|
||||||
Game, but it MUST NOT block replacement.
|
|
||||||
- The new Game MUST get a fresh VM session.
|
|
||||||
- The new Game MUST NOT inherit VM execution state, open handles, lifecycle
|
|
||||||
delivery state, cartridge identity, debug state, telemetry state, or crash
|
|
||||||
state from the previous Game.
|
|
||||||
- Render ownership MUST transition through SystemOS ownership policy and stale
|
|
||||||
submissions from the previous Game MUST NOT be presented after the switch.
|
|
||||||
- Input pending/barrier state MUST be cleared or made safe across the switch.
|
|
||||||
- App audio from the previous Game MUST be stopped or detached from the active
|
|
||||||
app before the new Game becomes foreground.
|
|
||||||
- Logs MAY remain as historical observability; they are not cartridge execution
|
|
||||||
state.
|
|
||||||
- If new Game load fails, Home/Hub is the recovery state for v1.
|
|
||||||
- V1 does not preserve, restore, or rollback to the previous Game after a
|
|
||||||
switch begins.
|
|
||||||
- The launcher target MAY be a path or already-resolved game-library entry for
|
|
||||||
v1. `.pmc` and final catalog UX are out of scope.
|
|
||||||
- `run_cart`, if retained, is not a userland command and not the switch
|
|
||||||
orchestrator.
|
|
||||||
|
|
||||||
## Impactos
|
|
||||||
|
|
||||||
- **Runtime / SystemOS:** needs an explicit Game switch orchestration path that
|
|
||||||
closes/removes the current resident Game session before loading the next Game.
|
|
||||||
- **Lifecycle:** needs a controlled replacement transition distinct from
|
|
||||||
pause/suspend/resume.
|
|
||||||
- **VM sessions:** previous Game session removal and new Game session creation
|
|
||||||
are mandatory switch steps.
|
|
||||||
- **Firmware:** should observe macro states such as Home, loading, load failure,
|
|
||||||
and GameRunning, but should not own switch policy.
|
|
||||||
- **Hub / launcher:** should request a switch through SystemOS using a resolved
|
|
||||||
target; it should not call a loader directly as lifecycle authority.
|
|
||||||
- **Loader:** remains a materialization step and returns success/failure without
|
|
||||||
owning cleanup policy.
|
|
||||||
- **Renderer:** render ownership/stale submission invalidation must prove the
|
|
||||||
new Game owns current presentation after success.
|
|
||||||
- **Input/audio:** previous Game input/audio must not leak into the new Game.
|
|
||||||
- **Tests:** need a second visually distinct test cartridge, `dummy-boy`, to
|
|
||||||
prove Game identity and render transition.
|
|
||||||
|
|
||||||
## Alternativas Descartadas
|
|
||||||
|
|
||||||
- **Preserve Game A until Game B loads successfully:** rejected for v1 because it
|
|
||||||
requires rollback semantics across VM, assets, handles, render ownership,
|
|
||||||
input, audio, debugger, and telemetry.
|
|
||||||
- **Treat Game A -> Game B as pause/resume:** rejected because a different Game
|
|
||||||
should not inherit resumable state from the previous Game.
|
|
||||||
- **Let the loader close the previous Game:** rejected because loader/materializer
|
|
||||||
should not own lifecycle policy.
|
|
||||||
- **Reuse the previous VM session for the new Game:** rejected because it
|
|
||||||
violates VM session ownership and risks state leakage.
|
|
||||||
- **Depend on `.pmc` or final catalog UX now:** rejected because the lifecycle
|
|
||||||
contract can be validated using path/game-library targets first.
|
|
||||||
|
|
||||||
## Referencias
|
|
||||||
|
|
||||||
- Source agenda: `AGD-0044`
|
|
||||||
- Foreground stack and Game pause contract: `DEC-0037`
|
|
||||||
- VM session ownership for VM-backed processes: `DEC-0038`
|
|
||||||
- SystemOS lifecycle/process/task authority: `DSC-0032`
|
|
||||||
- Launch authority lesson: `LSN-0051`
|
|
||||||
- Foreground/session ownership lesson: `LSN-0052`
|
|
||||||
|
|
||||||
## Propagacao Necessaria
|
|
||||||
|
|
||||||
- Add/update runtime spec for Game cartridge switching under SystemOS.
|
|
||||||
- Add implementation plans for:
|
|
||||||
- SystemOS switch orchestration;
|
|
||||||
- resident Game termination/session removal;
|
|
||||||
- fresh session load for the new Game;
|
|
||||||
- failure recovery to Home/Hub;
|
|
||||||
- `dummy-boy` test cartridge;
|
|
||||||
- end-to-end `Stress -> Home -> Dummy Boy` validation.
|
|
||||||
- Ensure host/debug direct boot remains separate from SystemOS Game switch.
|
|
||||||
@@ -1,86 +0,0 @@
|
|||||||
---
|
|
||||||
id: PLN-0157
|
|
||||||
ticket: system-os-cartridge-switch-orchestrator
|
|
||||||
title: Introduce SystemOS Game Switch Target Contract
|
|
||||||
status: done
|
|
||||||
created: 2026-07-05
|
|
||||||
ref_decisions: [DEC-0039]
|
|
||||||
tags: [runtime, os, lifecycle, game, cartridge, architecture]
|
|
||||||
---
|
|
||||||
|
|
||||||
## Briefing
|
|
||||||
|
|
||||||
DEC-0039 requires Game-to-Game switching under Home/Hub to be owned by SystemOS.
|
|
||||||
Before destructive replacement can be implemented, Hub/Firmware/SystemOS need a
|
|
||||||
small explicit contract for "launch this resolved Game target as a replacement"
|
|
||||||
that is separate from direct boot and from loader internals.
|
|
||||||
|
|
||||||
## Objective
|
|
||||||
|
|
||||||
Introduce a SystemOS-owned Game switch request/target abstraction that can carry
|
|
||||||
a resolved cartridge path or game-library entry from Hub/Home into the switch
|
|
||||||
orchestrator without making the loader or userland the lifecycle authority.
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
- Source decision: DEC-0039.
|
|
||||||
- Builds on DEC-0037 and DEC-0038 as already implemented.
|
|
||||||
- Must be implemented before PLN-0158, PLN-0159, and PLN-0161.
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
- Define a minimal Game switch target type, such as `GameSwitchTarget` or
|
|
||||||
`CartridgeLaunchTarget`, in the SystemOS/Firmware boundary.
|
|
||||||
- Route Hub game-library launch actions through that target contract instead of
|
|
||||||
treating a path as an implicit lifecycle operation.
|
|
||||||
- Keep direct boot/debug boot paths separate from SystemOS Game switching.
|
|
||||||
- Add tests proving the target preserves cartridge identity/path without
|
|
||||||
starting lifecycle replacement by itself.
|
|
||||||
|
|
||||||
## Non-Goals
|
|
||||||
|
|
||||||
- Do not implement destructive replacement in this plan.
|
|
||||||
- Do not add `.pmc`, final catalog UX, or a new launcher UI.
|
|
||||||
- Do not change direct CLI/debug boot behavior.
|
|
||||||
- Do not add background execution.
|
|
||||||
|
|
||||||
## Execution Method
|
|
||||||
|
|
||||||
1. Inspect `crates/console/prometeu-system/src/services/game_library.rs`,
|
|
||||||
`crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`,
|
|
||||||
and `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`.
|
|
||||||
2. Add a minimal launch target model at the SystemOS/Firmware boundary:
|
|
||||||
- resolved cartridge path;
|
|
||||||
- optional app_id/title metadata if already available;
|
|
||||||
- no loader-owned lifecycle policy.
|
|
||||||
3. Update Hub action plumbing so `SystemProfileAction::LaunchGame` carries the
|
|
||||||
resolved target type or maps immediately into it at the firmware boundary.
|
|
||||||
4. Add a placeholder SystemOS/Firmware entry point for Game switching that
|
|
||||||
accepts the target but still delegates to the existing load path until
|
|
||||||
PLN-0158 changes replacement behavior.
|
|
||||||
5. Add unit tests for target construction and path propagation.
|
|
||||||
6. Keep direct `BootTarget::Cartridge` behavior unchanged.
|
|
||||||
|
|
||||||
## Acceptance Criteria
|
|
||||||
|
|
||||||
- There is an explicit type or function contract representing a resolved
|
|
||||||
SystemOS Game switch target.
|
|
||||||
- Hub/Home no longer treats a raw path as lifecycle authority.
|
|
||||||
- The loader remains a materialization step, not the switch orchestrator.
|
|
||||||
- Direct boot/debug boot code paths remain separate and behaviorally unchanged.
|
|
||||||
- Tests prove target identity is carried without implicitly closing or loading a
|
|
||||||
Game.
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
- `cargo test -p prometeu-system`
|
|
||||||
- `cargo test -p prometeu-firmware`
|
|
||||||
- `cargo test -p prometeu-host-desktop-winit`
|
|
||||||
- `cargo clippy -p prometeu-system -p prometeu-firmware -p prometeu-host-desktop-winit --all-targets -- -D warnings`
|
|
||||||
|
|
||||||
## Affected Artifacts
|
|
||||||
|
|
||||||
- `crates/console/prometeu-system/src/services/game_library.rs`
|
|
||||||
- `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`
|
|
||||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
|
|
||||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
|
||||||
-98
@@ -1,98 +0,0 @@
|
|||||||
---
|
|
||||||
id: PLN-0158
|
|
||||||
ticket: system-os-cartridge-switch-orchestrator
|
|
||||||
title: Terminate Resident Game Before Switching Cartridges
|
|
||||||
status: done
|
|
||||||
created: 2026-07-05
|
|
||||||
ref_decisions: [DEC-0039]
|
|
||||||
tags: [runtime, os, lifecycle, game, cartridge, architecture]
|
|
||||||
---
|
|
||||||
|
|
||||||
## Briefing
|
|
||||||
|
|
||||||
DEC-0039 defines `Game A -> Home -> Game B` as destructive replacement. The
|
|
||||||
current same-Game resume flow keeps the resident Game session alive; switching
|
|
||||||
to a different Game must instead close/remove that resident session and create a
|
|
||||||
fresh session for the new Game.
|
|
||||||
|
|
||||||
## Objective
|
|
||||||
|
|
||||||
Implement the SystemOS lifecycle/session operation that terminates the current
|
|
||||||
resident Game before loading a different Game cartridge.
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
- Source decision: DEC-0039.
|
|
||||||
- Requires PLN-0157 target contract.
|
|
||||||
- Should be implemented before PLN-0159 and PLN-0161.
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
- Add a controlled resident Game termination/replacement operation to SystemOS
|
|
||||||
lifecycle/session services.
|
|
||||||
- Optionally emit a cooperative terminate/close/save lifecycle event when the
|
|
||||||
current event model can carry it, but do not block replacement on it.
|
|
||||||
- Remove the previous Game from resident/resumable state.
|
|
||||||
- Remove the previous Game VM session before activating the new Game.
|
|
||||||
- Clear or reassign app-scoped state that cannot leak into the new Game:
|
|
||||||
session VM, open handles, pending lifecycle state, input barrier/pending
|
|
||||||
input, audio active app state, render ownership, telemetry/debug/crash state.
|
|
||||||
|
|
||||||
## Non-Goals
|
|
||||||
|
|
||||||
- Do not preserve Game A for rollback.
|
|
||||||
- Do not implement failed-load recovery beyond surfacing errors; that is
|
|
||||||
PLN-0159.
|
|
||||||
- Do not add background execution or multiple resident Games.
|
|
||||||
- Do not build final launcher UX.
|
|
||||||
|
|
||||||
## Execution Method
|
|
||||||
|
|
||||||
1. Inspect lifecycle/session state in:
|
|
||||||
- `crates/console/prometeu-system/src/os/lifecycle.rs`;
|
|
||||||
- `crates/console/prometeu-system/src/os/facades/sessions.rs`;
|
|
||||||
- `crates/console/prometeu-system/src/services/foreground`;
|
|
||||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`;
|
|
||||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`.
|
|
||||||
2. Add a `replace_resident_game` or equivalent operation that:
|
|
||||||
- finds the current resident Game;
|
|
||||||
- marks its task/process closed or stopped according to existing lifecycle
|
|
||||||
semantics;
|
|
||||||
- removes the resident Game entry from foreground stack/lifecycle state;
|
|
||||||
- removes its VM session.
|
|
||||||
3. Ensure same-Game resume still bypasses replacement and remains governed by
|
|
||||||
DEC-0037.
|
|
||||||
4. Update game launch from Home so launching a different app_id triggers
|
|
||||||
replacement before load.
|
|
||||||
5. Ensure render ownership transitions away from the old Game before the new
|
|
||||||
Game becomes foreground.
|
|
||||||
6. Add focused tests for resident Game termination and session removal.
|
|
||||||
|
|
||||||
## Acceptance Criteria
|
|
||||||
|
|
||||||
- Launching a different Game from Home closes/removes the resident Game rather
|
|
||||||
than resuming it.
|
|
||||||
- The previous Game VM session is absent before the new Game is made active.
|
|
||||||
- Same-Game selection still resumes the existing resident Game.
|
|
||||||
- A cooperative close/terminate event, if added, is non-blocking.
|
|
||||||
- No previous Game VM, handle, lifecycle, render, or debug state is reused by
|
|
||||||
the new Game.
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
- `cargo test -p prometeu-system`
|
|
||||||
- `cargo test -p prometeu-firmware`
|
|
||||||
- `cargo clippy -p prometeu-system -p prometeu-firmware --all-targets -- -D warnings`
|
|
||||||
- Add tests for:
|
|
||||||
- different Game launch removes previous resident session;
|
|
||||||
- same Game launch resumes existing resident session;
|
|
||||||
- old Game task/process state is closed/stopped;
|
|
||||||
- old Game session cannot be resolved after replacement starts.
|
|
||||||
|
|
||||||
## Affected Artifacts
|
|
||||||
|
|
||||||
- `crates/console/prometeu-system/src/os/lifecycle.rs`
|
|
||||||
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
|
||||||
- `crates/console/prometeu-system/src/services/foreground`
|
|
||||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
|
|
||||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
|
|
||||||
@@ -1,86 +0,0 @@
|
|||||||
---
|
|
||||||
id: PLN-0159
|
|
||||||
ticket: system-os-cartridge-switch-orchestrator
|
|
||||||
title: Recover Failed Game Switches Back To Home
|
|
||||||
status: open
|
|
||||||
created: 2026-07-05
|
|
||||||
ref_decisions: [DEC-0039]
|
|
||||||
tags: [runtime, os, lifecycle, game, cartridge, architecture]
|
|
||||||
---
|
|
||||||
|
|
||||||
## Briefing
|
|
||||||
|
|
||||||
DEC-0039 rejects preserving Game A after a switch begins. If Game B fails to
|
|
||||||
load, the system must discard partial Game B state and return to Home/Hub with a
|
|
||||||
diagnostic, not attempt rollback to Game A.
|
|
||||||
|
|
||||||
## Objective
|
|
||||||
|
|
||||||
Implement controlled failed-switch recovery to Home/Hub after destructive Game
|
|
||||||
replacement begins.
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
- Source decision: DEC-0039.
|
|
||||||
- Requires PLN-0157 target contract.
|
|
||||||
- Requires PLN-0158 resident Game termination/session removal.
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
- Detect load/init failure while switching to a different Game.
|
|
||||||
- Discard any partial new Game task/session/window/render/input/audio state.
|
|
||||||
- Return firmware/SystemOS to Home/Hub.
|
|
||||||
- Log or expose a diagnostic that Home can surface or tests can assert.
|
|
||||||
- Ensure previous Game is not restored after switch failure.
|
|
||||||
|
|
||||||
## Non-Goals
|
|
||||||
|
|
||||||
- Do not implement transactional rollback.
|
|
||||||
- Do not preserve the previous Game after switch begins.
|
|
||||||
- Do not design final user-facing error UI.
|
|
||||||
- Do not change direct boot failure behavior unless needed to keep paths
|
|
||||||
separate.
|
|
||||||
|
|
||||||
## Execution Method
|
|
||||||
|
|
||||||
1. Inspect existing load failure flow in
|
|
||||||
`crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`.
|
|
||||||
2. Add a switch-specific failure outcome or context flag that distinguishes
|
|
||||||
SystemOS Game switching from direct boot load.
|
|
||||||
3. On switch load failure:
|
|
||||||
- remove partial new VM session/task/process if created;
|
|
||||||
- clear partial cartridge-scoped state;
|
|
||||||
- transition to `HubHome` instead of app crash when appropriate for switch
|
|
||||||
recovery;
|
|
||||||
- log a diagnostic containing target identity/path and failure summary.
|
|
||||||
4. Preserve existing direct boot and explicit load failure tests unless a direct
|
|
||||||
boot path intentionally still goes to crash.
|
|
||||||
5. Add tests for bad Game B after Game A was already terminated.
|
|
||||||
|
|
||||||
## Acceptance Criteria
|
|
||||||
|
|
||||||
- Failed `Game A -> Home -> Broken Game B` returns to Home/Hub.
|
|
||||||
- Previous Game A is not resident, resumable, or restored.
|
|
||||||
- Partial Game B VM session/task/process state is removed or closed.
|
|
||||||
- A diagnostic is logged or otherwise observable.
|
|
||||||
- Existing direct boot/debug boot failure semantics remain separate.
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
- `cargo test -p prometeu-firmware`
|
|
||||||
- `cargo test -p prometeu-system`
|
|
||||||
- `cargo test -p prometeu-host-desktop-winit`
|
|
||||||
- `cargo clippy -p prometeu-system -p prometeu-firmware -p prometeu-host-desktop-winit --all-targets -- -D warnings`
|
|
||||||
- Add tests for:
|
|
||||||
- switch failure returns Home;
|
|
||||||
- old Game not restored;
|
|
||||||
- partial new session cleanup;
|
|
||||||
- direct boot failure path remains unchanged.
|
|
||||||
|
|
||||||
## Affected Artifacts
|
|
||||||
|
|
||||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
|
|
||||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
|
|
||||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
|
||||||
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
|
||||||
- `crates/console/prometeu-system/src/os/lifecycle.rs`
|
|
||||||
@@ -1,90 +0,0 @@
|
|||||||
---
|
|
||||||
id: PLN-0160
|
|
||||||
ticket: system-os-cartridge-switch-orchestrator
|
|
||||||
title: Add Dummy Boy Visual Switch Test Cartridge
|
|
||||||
status: open
|
|
||||||
created: 2026-07-05
|
|
||||||
ref_decisions: [DEC-0039]
|
|
||||||
tags: [runtime, os, lifecycle, game, cartridge, architecture]
|
|
||||||
---
|
|
||||||
|
|
||||||
## Briefing
|
|
||||||
|
|
||||||
DEC-0039 requires minimum evidence using two distinct test cartridges. The
|
|
||||||
existing stress cartridge proves execution/logging but is not visually distinct
|
|
||||||
enough for switch validation. A second cartridge, `dummy-boy`, must render an
|
|
||||||
oscillating-color square.
|
|
||||||
|
|
||||||
## Objective
|
|
||||||
|
|
||||||
Add a simple `test-cartridges/dummy-boy` cartridge that renders a visible square
|
|
||||||
with changing colors so Game switching can prove visual/session identity.
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
- Source decision: DEC-0039.
|
|
||||||
- Can be implemented independently of PLN-0157 through PLN-0159.
|
|
||||||
- Required before PLN-0161 end-to-end validation.
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
- Add `test-cartridges/dummy-boy/manifest.json`.
|
|
||||||
- Generate or add `test-cartridges/dummy-boy/program.pbx`.
|
|
||||||
- Add empty or minimal assets payload if the loader requires `assets.pa`.
|
|
||||||
- Implement Dummy Boy behavior:
|
|
||||||
- Game cartridge identity distinct from stress;
|
|
||||||
- deterministic visible square;
|
|
||||||
- color oscillates across frames;
|
|
||||||
- no dependency on final launcher UX.
|
|
||||||
- Add build/generation documentation or tests so the cartridge can be
|
|
||||||
regenerated safely if needed.
|
|
||||||
|
|
||||||
## Non-Goals
|
|
||||||
|
|
||||||
- Do not add final game content.
|
|
||||||
- Do not add `.pmc`.
|
|
||||||
- Do not depend on host screenshots for the first validation unless an existing
|
|
||||||
harness already supports it.
|
|
||||||
- Do not change stress cartridge behavior.
|
|
||||||
|
|
||||||
## Execution Method
|
|
||||||
|
|
||||||
1. Inspect the stress cartridge and any PBX generator tooling:
|
|
||||||
- `test-cartridges/stress-console`;
|
|
||||||
- `crates/tools/pbxgen-stress`;
|
|
||||||
- bytecode assembler helpers in `crates/console/prometeu-bytecode`.
|
|
||||||
2. Choose the smallest maintainable generator path:
|
|
||||||
- extend existing PBX generator if appropriate; or
|
|
||||||
- add a focused `pbxgen-dummy-boy` tool; or
|
|
||||||
- add deterministic generated PBX with source instructions.
|
|
||||||
3. Create `manifest.json` with unique `app_id`, title `Dummy Boy`, Game mode,
|
|
||||||
and version.
|
|
||||||
4. Generate `program.pbx` that renders the square and advances color over
|
|
||||||
frames.
|
|
||||||
5. Add tests or smoke checks that the cartridge is discoverable by games-root
|
|
||||||
discovery.
|
|
||||||
|
|
||||||
## Acceptance Criteria
|
|
||||||
|
|
||||||
- `test-cartridges/dummy-boy` exists and loads as a Game cartridge.
|
|
||||||
- Dummy Boy has a unique `app_id` and title distinct from Stress.
|
|
||||||
- Dummy Boy renders a visible square.
|
|
||||||
- Square color changes deterministically over time.
|
|
||||||
- Games-root discovery sees both Stress and Dummy Boy.
|
|
||||||
- Existing stress cartridge remains unchanged.
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
- `cargo test -p prometeu-hal`
|
|
||||||
- `cargo test -p prometeu-system`
|
|
||||||
- `cargo test -p prometeu-firmware`
|
|
||||||
- Run any cartridge generator tests added by this plan.
|
|
||||||
- Add or update tests for games-root discovery including Dummy Boy.
|
|
||||||
|
|
||||||
## Affected Artifacts
|
|
||||||
|
|
||||||
- `test-cartridges/dummy-boy/manifest.json`
|
|
||||||
- `test-cartridges/dummy-boy/program.pbx`
|
|
||||||
- `test-cartridges/dummy-boy/assets.pa` if required
|
|
||||||
- `crates/tools/*` cartridge generator tooling if needed
|
|
||||||
- `crates/console/prometeu-system/src/services/game_library.rs` tests if needed
|
|
||||||
-93
@@ -1,93 +0,0 @@
|
|||||||
---
|
|
||||||
id: PLN-0161
|
|
||||||
ticket: system-os-cartridge-switch-orchestrator
|
|
||||||
title: Validate Stress To Dummy Boy Game Switch End To End
|
|
||||||
status: open
|
|
||||||
created: 2026-07-05
|
|
||||||
ref_decisions: [DEC-0039]
|
|
||||||
tags: [runtime, os, lifecycle, game, cartridge, architecture]
|
|
||||||
---
|
|
||||||
|
|
||||||
## Briefing
|
|
||||||
|
|
||||||
DEC-0039 requires proof that `Game A -> Home -> Game B` creates a fresh Game
|
|
||||||
session and does not present stale state from Game A. The minimum evidence is
|
|
||||||
switching from Stress to Dummy Boy.
|
|
||||||
|
|
||||||
## Objective
|
|
||||||
|
|
||||||
Add end-to-end validation for `Stress -> Home -> Dummy Boy` through the real
|
|
||||||
Hub/Home flow, proving lifecycle, VM session, cartridge identity, and render
|
|
||||||
ownership switch correctly.
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
- Source decision: DEC-0039.
|
|
||||||
- Requires PLN-0157 target contract.
|
|
||||||
- Requires PLN-0158 destructive replacement.
|
|
||||||
- Requires PLN-0159 failed-switch recovery for negative path assertions.
|
|
||||||
- Requires PLN-0160 Dummy Boy cartridge.
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
- Add firmware/system tests that drive:
|
|
||||||
- launch Stress from games root;
|
|
||||||
- request Home;
|
|
||||||
- launch Dummy Boy;
|
|
||||||
- assert Stress session is gone;
|
|
||||||
- assert Dummy Boy session is active;
|
|
||||||
- assert cartridge identity and render ownership belong to Dummy Boy.
|
|
||||||
- Add a negative end-to-end test for broken Game B returning to Home if not
|
|
||||||
already covered by PLN-0159.
|
|
||||||
- Use existing test platform/render submission inspection where possible.
|
|
||||||
|
|
||||||
## Non-Goals
|
|
||||||
|
|
||||||
- Do not require final launcher UX.
|
|
||||||
- Do not add screenshot-based host automation unless existing test utilities
|
|
||||||
make it cheap and deterministic.
|
|
||||||
- Do not implement additional Game-to-Game variants beyond Stress to Dummy Boy.
|
|
||||||
|
|
||||||
## Execution Method
|
|
||||||
|
|
||||||
1. Inspect existing firmware tests in
|
|
||||||
`crates/console/prometeu-firmware/src/firmware/firmware.rs`.
|
|
||||||
2. Reuse existing `TestGameRoot` or games-root helpers to expose Stress and
|
|
||||||
Dummy Boy.
|
|
||||||
3. Drive input through Hub/Home selection rather than calling cartridge load
|
|
||||||
directly when possible.
|
|
||||||
4. Assert lifecycle/session invariants:
|
|
||||||
- old task closed/stopped;
|
|
||||||
- old VM session removed;
|
|
||||||
- new VM session created;
|
|
||||||
- foreground owner is new Game;
|
|
||||||
- current cartridge identity is Dummy Boy.
|
|
||||||
5. Assert render invariants:
|
|
||||||
- render ownership epoch belongs to Dummy Boy app identity;
|
|
||||||
- stale Stress submissions are not accepted after switch;
|
|
||||||
- latest observable Game frame comes from Dummy Boy when render inspection is
|
|
||||||
available.
|
|
||||||
6. Add a focused test for failure path if missing after PLN-0159.
|
|
||||||
|
|
||||||
## Acceptance Criteria
|
|
||||||
|
|
||||||
- End-to-end test proves Stress can be replaced by Dummy Boy from Home.
|
|
||||||
- Stress is not resumable after switching to Dummy Boy.
|
|
||||||
- Dummy Boy receives a fresh VM session.
|
|
||||||
- Cartridge identity and active render ownership are Dummy Boy after switch.
|
|
||||||
- Failure path returns Home and does not restore Stress.
|
|
||||||
- Tests are deterministic and do not rely on manual host interaction.
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
- `cargo test -p prometeu-firmware`
|
|
||||||
- `cargo test -p prometeu-system`
|
|
||||||
- `cargo test -p prometeu-host-desktop-winit`
|
|
||||||
- `cargo clippy -p prometeu-system -p prometeu-firmware -p prometeu-host-desktop-winit --all-targets -- -D warnings`
|
|
||||||
|
|
||||||
## Affected Artifacts
|
|
||||||
|
|
||||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
|
||||||
- `crates/console/prometeu-system/src/services/game_library.rs`
|
|
||||||
- `test-cartridges/dummy-boy`
|
|
||||||
- Host/render test utilities if needed
|
|
||||||
-93
@@ -1,93 +0,0 @@
|
|||||||
---
|
|
||||||
id: PLN-0162
|
|
||||||
ticket: system-os-cartridge-switch-orchestrator
|
|
||||||
title: Specify Game Switch Contract And Direct Boot Separation
|
|
||||||
status: open
|
|
||||||
created: 2026-07-05
|
|
||||||
ref_decisions: [DEC-0039]
|
|
||||||
tags: [runtime, os, lifecycle, game, cartridge, architecture]
|
|
||||||
---
|
|
||||||
|
|
||||||
## Briefing
|
|
||||||
|
|
||||||
DEC-0039 must be reflected in the canonical runtime specs after the operational
|
|
||||||
contract is implemented or alongside implementation. The spec must distinguish
|
|
||||||
same-Game resume, Game replacement under SystemOS, and direct boot/debug boot.
|
|
||||||
|
|
||||||
## Objective
|
|
||||||
|
|
||||||
Update the canonical runtime documentation to describe SystemOS Game cartridge
|
|
||||||
switching and to keep direct boot/debug boot separate from Home/Hub-driven Game
|
|
||||||
replacement.
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
- Source decision: DEC-0039.
|
|
||||||
- Can be implemented before code if the spec is written as intended behavior.
|
|
||||||
- Should be reconciled after PLN-0157 through PLN-0161 if implementation names
|
|
||||||
differ from initial plan names.
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
- Update relevant files under `docs/specs/runtime/`, especially:
|
|
||||||
- `12-firmware-pos-and-prometeuhub.md`;
|
|
||||||
- `13-cartridge.md`;
|
|
||||||
- `14-boot-profiles.md`;
|
|
||||||
- `09-events-and-concurrency.md` if lifecycle events need mention;
|
|
||||||
- `10-debug-inspection-and-profiling.md` if debugger separation needs note.
|
|
||||||
- Document:
|
|
||||||
- SystemOS authority for Game switching;
|
|
||||||
- destructive replacement semantics;
|
|
||||||
- optional non-blocking terminate/save event;
|
|
||||||
- fresh VM session for new Game;
|
|
||||||
- failed switch recovery to Home/Hub;
|
|
||||||
- direct boot/debug boot separation;
|
|
||||||
- test cartridge evidence requirement.
|
|
||||||
|
|
||||||
## Non-Goals
|
|
||||||
|
|
||||||
- Do not document `.pmc` or final catalog UX as required.
|
|
||||||
- Do not specify background execution.
|
|
||||||
- Do not revise DEC-0037 or DEC-0038 semantics.
|
|
||||||
- Do not write lesson material; housekeeping will decide lessons after
|
|
||||||
execution.
|
|
||||||
|
|
||||||
## Execution Method
|
|
||||||
|
|
||||||
1. Read the runtime spec files listed in scope.
|
|
||||||
2. Add a Game switching section in the most appropriate canonical spec file.
|
|
||||||
3. Cross-reference existing Home/Hub, cartridge, boot profile, and debug boot
|
|
||||||
sections.
|
|
||||||
4. Ensure language is English and normative enough for future implementers:
|
|
||||||
`MUST`, `MUST NOT`, `MAY`, `SHOULD`.
|
|
||||||
5. Verify no non-English agenda language leaks into specs.
|
|
||||||
6. Run docs grep checks for the newly introduced terms.
|
|
||||||
|
|
||||||
## Acceptance Criteria
|
|
||||||
|
|
||||||
- Specs explicitly distinguish:
|
|
||||||
- same-Game pause/resume;
|
|
||||||
- Game A to Game B destructive replacement;
|
|
||||||
- direct boot/debug boot.
|
|
||||||
- Specs state that SystemOS owns Game switching policy.
|
|
||||||
- Specs state that a new Game gets a fresh VM session.
|
|
||||||
- Specs state that failed switch returns Home/Hub and does not restore the old
|
|
||||||
Game in v1.
|
|
||||||
- Specs mention Dummy Boy or equivalent two-cartridge evidence only as test
|
|
||||||
evidence, not as runtime feature.
|
|
||||||
- Documentation is English.
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
- `rg -n "Game switch|destructive replacement|direct boot|Dummy Boy|VM session" docs/specs/runtime`
|
|
||||||
- `discussion validate`
|
|
||||||
- Run code tests only if this plan is implemented together with code changes:
|
|
||||||
`cargo test -p prometeu-system -p prometeu-firmware`
|
|
||||||
|
|
||||||
## Affected Artifacts
|
|
||||||
|
|
||||||
- `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md`
|
|
||||||
- `docs/specs/runtime/13-cartridge.md`
|
|
||||||
- `docs/specs/runtime/14-boot-profiles.md`
|
|
||||||
- `docs/specs/runtime/09-events-and-concurrency.md`
|
|
||||||
- `docs/specs/runtime/10-debug-inspection-and-profiling.md`
|
|
||||||
@@ -625,7 +625,8 @@ Each tilemap cell contains:
|
|||||||
|
|
||||||
Runtime-facing validity rule for v1:
|
Runtime-facing validity rule for v1:
|
||||||
|
|
||||||
- `palette_id` values are valid only in the range `0..63`
|
- `palette_id` values are valid only when `palette_id < palette_count` for the
|
||||||
|
resolved resident glyph bank
|
||||||
|
|
||||||
#### Sprite
|
#### Sprite
|
||||||
|
|
||||||
@@ -640,7 +641,8 @@ Each sprite draw contains:
|
|||||||
|
|
||||||
Runtime-facing validity rule for v1:
|
Runtime-facing validity rule for v1:
|
||||||
|
|
||||||
- `palette_id` values are valid only in the range `0..63`
|
- `palette_id` values are valid only when `palette_id < palette_count` for the
|
||||||
|
referenced resident glyph bank
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -649,7 +651,7 @@ Runtime-facing validity rule for v1:
|
|||||||
The pipeline works like this:
|
The pipeline works like this:
|
||||||
|
|
||||||
1. Read indexed pixel from tile (value 0..15)
|
1. Read indexed pixel from tile (value 0..15)
|
||||||
2. Resolve:
|
2. Validate and resolve:
|
||||||
- real_color = palette[palette_id][index]
|
- real_color = palette[palette_id][index]
|
||||||
3. Apply:
|
3. Apply:
|
||||||
- flip
|
- flip
|
||||||
@@ -667,6 +669,9 @@ else:
|
|||||||
draw_or_blend(color)
|
draw_or_blend(color)
|
||||||
```
|
```
|
||||||
|
|
||||||
|
The `palette_id` lookup above is valid only after the runtime has established
|
||||||
|
that the referenced resident glyph bank contains that palette.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 19.7. Organization of Tile Banks
|
### 19.7. Organization of Tile Banks
|
||||||
@@ -766,6 +771,8 @@ Rules:
|
|||||||
- missing glyph dependencies referenced by a resident scene are not a passive `status:int` case;
|
- missing glyph dependencies referenced by a resident scene are not a passive `status:int` case;
|
||||||
- if scene activation discovers that a layer dependency cannot be resolved to a committed glyph asset, the machine MUST fail fatally and emit a clear log;
|
- if scene activation discovers that a layer dependency cannot be resolved to a committed glyph asset, the machine MUST fail fatally and emit a clear log;
|
||||||
- if scene composition later discovers that a layer dependency can no longer be resolved, the machine MUST fail fatally and emit a clear log;
|
- if scene composition later discovers that a layer dependency can no longer be resolved, the machine MUST fail fatally and emit a clear log;
|
||||||
|
- if scene activation or composition discovers that a tile references `palette_id >= palette_count` for its resolved glyph bank, the machine MUST fail fatally and emit a clear log;
|
||||||
|
- invalid scene palette references are scene dependency failures and MUST NOT be rendered through transparent, black, or default color substitution;
|
||||||
- runtime MUST NOT continue canonical scene composition after such a dependency failure.
|
- runtime MUST NOT continue canonical scene composition after such a dependency failure.
|
||||||
|
|
||||||
### 20.2 `composer.emit_sprite`
|
### 20.2 `composer.emit_sprite`
|
||||||
@@ -774,7 +781,7 @@ Rules:
|
|||||||
|
|
||||||
ABI:
|
ABI:
|
||||||
1. `glyph_id: int` — glyph index within the bank
|
1. `glyph_id: int` — glyph index within the bank
|
||||||
2. `palette_id: int` — palette index
|
2. `palette_id: int` — palette index within the referenced bank; valid only when `palette_id < palette_count` for that resident glyph bank
|
||||||
3. `x: int` — x coordinate
|
3. `x: int` — x coordinate
|
||||||
4. `y: int` — y coordinate
|
4. `y: int` — y coordinate
|
||||||
5. `layer: int` — composition layer reference
|
5. `layer: int` — composition layer reference
|
||||||
@@ -797,4 +804,6 @@ Operational notes:
|
|||||||
- the canonical public sprite contract is frame-emission based;
|
- the canonical public sprite contract is frame-emission based;
|
||||||
- no caller-provided sprite index exists in the v1 canonical ABI;
|
- no caller-provided sprite index exists in the v1 canonical ABI;
|
||||||
- no `active` flag exists in the v1 canonical ABI;
|
- no `active` flag exists in the v1 canonical ABI;
|
||||||
|
- `palette_id >= palette_count` for the referenced glyph bank MUST return `BANK_INVALID`;
|
||||||
|
- invalid sprite palette references MUST NOT be rendered through transparent, black, or default color substitution;
|
||||||
- overflow remains non-fatal and must not escalate to trap in v1.
|
- overflow remains non-fatal and must not escalate to trap in v1.
|
||||||
|
|||||||
@@ -128,6 +128,11 @@ SystemOS resume request
|
|||||||
scheduler/runtime state. A Game may observe pause/resume, but it must not
|
scheduler/runtime state. A Game may observe pause/resume, but it must not
|
||||||
control whether SystemOS suspends or resumes the VM.
|
control whether SystemOS suspends or resumes the VM.
|
||||||
|
|
||||||
|
When SystemOS replaces one Game with another from Home, the old Game MAY receive
|
||||||
|
a cooperative terminate/save lifecycle event if the runtime supports such an
|
||||||
|
event. That event is non-blocking in v1. SystemOS remains authoritative and may
|
||||||
|
close the old Game task/session without guest acknowledgement.
|
||||||
|
|
||||||
Pause budgets are measured in deterministic machine units, not host wall-clock
|
Pause budgets are measured in deterministic machine units, not host wall-clock
|
||||||
time. A suspended Game receives no normal gameplay ticks, no normal Game input,
|
time. A suspended Game receives no normal gameplay ticks, no normal Game input,
|
||||||
and no frame pacing. Real background execution is outside the v1 foreground
|
and no frame pacing. Real background execution is outside the v1 foreground
|
||||||
@@ -163,6 +168,20 @@ requires it. Transient VM handles, open files, lifecycle delivery queues, and
|
|||||||
staging state are session-scoped unless another spec explicitly makes them
|
staging state are session-scoped unless another spec explicitly makes them
|
||||||
durable app data.
|
durable app data.
|
||||||
|
|
||||||
|
During destructive Game replacement, the old Game VM session MUST be removed
|
||||||
|
from execution eligibility and resumable state before the new Game becomes the
|
||||||
|
foreground Game. The new Game MUST receive a fresh VM session. Failure while
|
||||||
|
loading or initializing the replacement Game MUST return the machine to
|
||||||
|
Hub/Home and MUST NOT restore the previous Game in v1.
|
||||||
|
|
||||||
|
Manual Hub termination of a suspended resident Game has the same session
|
||||||
|
removal authority as destructive Game replacement, except that no replacement
|
||||||
|
Game is started. SystemOS MUST remove the Game from execution eligibility and
|
||||||
|
resumable state, close its task, stop its process, remove its VM session, clear
|
||||||
|
task-scoped pending lifecycle delivery, and keep Hub/Home as the foreground
|
||||||
|
owner. After manual Hub termination, resume queries MUST report no resident
|
||||||
|
Game. A later launch of the same cartridge is a fresh Game session.
|
||||||
|
|
||||||
## 9 Render Worker Concurrency
|
## 9 Render Worker Concurrency
|
||||||
|
|
||||||
The render worker is not a machine-visible event source and does not introduce
|
The render worker is not a machine-visible event source and does not introduce
|
||||||
|
|||||||
@@ -44,6 +44,11 @@ PROMETEU operates in three main modes:
|
|||||||
|
|
||||||
No mode alters the logical result of the program.
|
No mode alters the logical result of the program.
|
||||||
|
|
||||||
|
Debug boot is a host-selected direct cartridge boot profile. It follows the same
|
||||||
|
cartridge/app-mode resolution path as direct boot and is separate from
|
||||||
|
Home-driven Game switching. Debug boot MUST NOT be modeled as a guest-visible
|
||||||
|
Game switch request and MUST NOT reuse a Home switch failure-recovery contract.
|
||||||
|
|
||||||
## 3 Execution Control
|
## 3 Execution Control
|
||||||
|
|
||||||
### 3.1 Pause and Resume
|
### 3.1 Pause and Resume
|
||||||
|
|||||||
@@ -43,6 +43,9 @@ The VM does not own the machine lifecycle. Firmware does.
|
|||||||
Game directory cartridges.
|
Game directory cartridges.
|
||||||
- **Library entry**: an internal catalog record retained by Hub/SystemOS for a
|
- **Library entry**: an internal catalog record retained by Hub/SystemOS for a
|
||||||
discovered cartridge.
|
discovered cartridge.
|
||||||
|
- **Game switch target**: a SystemOS-owned launch target derived from a library
|
||||||
|
entry. It carries the cartridge path plus resolved identity such as `app_id`,
|
||||||
|
`title`, and `app_version`.
|
||||||
- **Foreground visual owner**: the single machine owner whose visual output may
|
- **Foreground visual owner**: the single machine owner whose visual output may
|
||||||
be presented at a given time.
|
be presented at a given time.
|
||||||
- **Paused**: a Game-visible lifecycle event/state. The Game may observe it and
|
- **Paused**: a Game-visible lifecycle event/state. The Game may observe it and
|
||||||
@@ -52,6 +55,8 @@ The VM does not own the machine lifecycle. Firmware does.
|
|||||||
frame pacing.
|
frame pacing.
|
||||||
- **VM session**: the POS-owned mutable execution context for one VM-backed
|
- **VM session**: the POS-owned mutable execution context for one VM-backed
|
||||||
process. It contains the VM instance and per-session runtime state.
|
process. It contains the VM instance and per-session runtime state.
|
||||||
|
- **Hub resident Game kill control**: a Hub/Home affordance that terminates the
|
||||||
|
current resident Game instead of resuming it.
|
||||||
|
|
||||||
## 3 POS Responsibilities
|
## 3 POS Responsibilities
|
||||||
|
|
||||||
@@ -86,6 +91,8 @@ PrometeuHub is responsible for:
|
|||||||
- presenting the host-provided local games library when `--games-root <dir>` is
|
- presenting the host-provided local games library when `--games-root <dir>` is
|
||||||
configured;
|
configured;
|
||||||
- emitting system-owned launch actions for selected Home entries.
|
- emitting system-owned launch actions for selected Home entries.
|
||||||
|
- presenting a resident Game kill control while Hub/Home owns foreground and a
|
||||||
|
Game is resident/suspended.
|
||||||
|
|
||||||
The Hub does not execute bytecode directly. It always delegates execution setup to POS.
|
The Hub does not execute bytecode directly. It always delegates execution setup to POS.
|
||||||
|
|
||||||
@@ -216,6 +223,17 @@ It preserves Game VM state but is not execution-eligible except for the bounded
|
|||||||
pause handoff and later foreground resume. A VM-backed Shell has a separate VM
|
pause handoff and later foreground resume. A VM-backed Shell has a separate VM
|
||||||
session. A native Shell has no VM session.
|
session. A native Shell has no VM session.
|
||||||
|
|
||||||
|
When Hub/Home is foreground and a Game cartridge remains resident/suspended,
|
||||||
|
PrometeuHub MUST render a red control in the bottom-right of the Hub viewport.
|
||||||
|
The control MUST display only the resident Game title. It MUST NOT be rendered
|
||||||
|
for no resident Game, Shell tasks, System tasks, or native Shell tasks.
|
||||||
|
|
||||||
|
Clicking the Hub resident Game kill control is a system-owned immediate
|
||||||
|
termination request. Firmware MUST keep the user in Hub/Home, MUST NOT ask for
|
||||||
|
confirmation in v1, and MUST NOT resume the killed Game on subsequent Home
|
||||||
|
actions. The control MUST disappear on the next Hub frame after the resident
|
||||||
|
Game is no longer present.
|
||||||
|
|
||||||
## 8 Cartridge Load Flow
|
## 8 Cartridge Load Flow
|
||||||
|
|
||||||
Current high-level flow:
|
Current high-level flow:
|
||||||
@@ -231,11 +249,51 @@ Current high-level flow:
|
|||||||
If VM initialization fails, firmware transitions to the crash path.
|
If VM initialization fails, firmware transitions to the crash path.
|
||||||
|
|
||||||
For v1, POS must enforce at most one resident Game session. Selecting the same
|
For v1, POS must enforce at most one resident Game session. Selecting the same
|
||||||
resident Game from Home resumes that session. Selecting a different Game while a
|
resident Game from Home resumes that session. Selecting a different Game from
|
||||||
resident Game exists is outside the v1 foreground contract and must not create a
|
Home is a SystemOS-owned Game switch and MUST be destructive replacement:
|
||||||
second resident Game session. VM-backed Shell loading creates a distinct Shell
|
|
||||||
|
```text
|
||||||
|
Game A resident
|
||||||
|
-> Hub/Home selected Game B with different app_id
|
||||||
|
-> SystemOS terminates Game A resident task/session
|
||||||
|
-> SystemOS removes Game A from resumable state
|
||||||
|
-> firmware loads Game B through LoadCartridge
|
||||||
|
-> Game B receives a fresh VM session
|
||||||
|
```
|
||||||
|
|
||||||
|
SystemOS MUST NOT create a second resident Game session. SystemOS MUST NOT
|
||||||
|
reuse the old Game VM session, transient VM handles, pending lifecycle delivery
|
||||||
|
state, render ownership, debug pause state, or crash/debug runtime state for the
|
||||||
|
new Game. Durable app data remains governed by the relevant storage specs and
|
||||||
|
may still be keyed by `app_id`.
|
||||||
|
|
||||||
|
SystemOS MAY emit a cooperative non-blocking terminate/save lifecycle event
|
||||||
|
before closing the old Game when such an event exists. Replacement MUST NOT
|
||||||
|
block on that event in v1. VM-backed Shell loading creates a distinct Shell
|
||||||
session and must not overwrite resident Game VM state.
|
session and must not overwrite resident Game VM state.
|
||||||
|
|
||||||
|
Manual Hub resident Game kill and destructive different-Game replacement MUST
|
||||||
|
share the canonical resident-Game termination path. That path MUST:
|
||||||
|
|
||||||
|
- close the resident Game task;
|
||||||
|
- mark its process stopped;
|
||||||
|
- remove its VM session;
|
||||||
|
- clear resident Game state and pending Game lifecycle delivery for that task;
|
||||||
|
- keep or return foreground ownership to Hub/Home;
|
||||||
|
- transition render ownership to Shell/Hub (`AppMode::Shell`, `app_id = 0`);
|
||||||
|
- clear the Game lifecycle audio pause state;
|
||||||
|
- unbind the Game2D frame composer scene;
|
||||||
|
- shut down cartridge-scoped asset manager state, including slot identity and
|
||||||
|
physical glyph/scene/sound banks.
|
||||||
|
|
||||||
|
After this operation, the killed Game MUST NOT be resumable. Launching that
|
||||||
|
same Game again from Home is a fresh cartridge load and a fresh VM session.
|
||||||
|
Manual Hub kill MUST emit an INFO Hub log with the message shape:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Resident game killed from Hub: <title>
|
||||||
|
```
|
||||||
|
|
||||||
POS selects the cartridge and its execution context, but the cartridge's initial callable is not chosen by firmware metadata. Execution starts from the cartridge boot protocol defined in [`13-cartridge.md`](13-cartridge.md), currently `func_id = 0`.
|
POS selects the cartridge and its execution context, but the cartridge's initial callable is not chosen by firmware metadata. Execution starts from the cartridge boot protocol defined in [`13-cartridge.md`](13-cartridge.md), currently `func_id = 0`.
|
||||||
|
|
||||||
When Home launches a discovered Game entry, the request is a system-owned action
|
When Home launches a discovered Game entry, the request is a system-owned action
|
||||||
@@ -248,6 +306,16 @@ If the selected cartridge cannot be loaded, firmware must leave or return the
|
|||||||
machine in the Hub/Home flow and record the failure through diagnostics or
|
machine in the Hub/Home flow and record the failure through diagnostics or
|
||||||
logging. A polished Home error surface is not required by v1.
|
logging. A polished Home error surface is not required by v1.
|
||||||
|
|
||||||
|
If a destructive Game switch has already begun and the new Game fails to load or
|
||||||
|
initialize, firmware MUST return to Hub/Home, MUST discard any partial new Game
|
||||||
|
task/session/window/render/input/audio state, and MUST NOT restore the previous
|
||||||
|
Game. Direct boot and debug boot failures remain governed by the boot profile
|
||||||
|
that requested them and may still transition to the crash path.
|
||||||
|
|
||||||
|
Switch validation MUST include two distinct Game cartridges. The current
|
||||||
|
repository evidence uses `Stress Console` and `Dummy Boy`; those cartridges are
|
||||||
|
test evidence, not required runtime features.
|
||||||
|
|
||||||
## 9 Firmware States
|
## 9 Firmware States
|
||||||
|
|
||||||
The current firmware state model includes:
|
The current firmware state model includes:
|
||||||
@@ -310,6 +378,9 @@ Expected behavior:
|
|||||||
resident Game session;
|
resident Game session;
|
||||||
- returning to the same Game resumes it through the foreground lifecycle and
|
- returning to the same Game resumes it through the foreground lifecycle and
|
||||||
waits for current-epoch Game rendering before visual Game presentation.
|
waits for current-epoch Game rendering before visual Game presentation.
|
||||||
|
- clicking the red bottom-right resident Game kill control terminates the
|
||||||
|
resident Game, keeps Home foreground, clears runtime/cartridge residue, and
|
||||||
|
removes the resume path.
|
||||||
|
|
||||||
## 13 Relationship to Other Specs
|
## 13 Relationship to Other Specs
|
||||||
|
|
||||||
|
|||||||
@@ -186,6 +186,9 @@ For the v1 Home games library:
|
|||||||
- the manifest must declare `app_mode: "Game"`;
|
- the manifest must declare `app_mode: "Game"`;
|
||||||
- the library retains the loaded manifest data, `title`, `app_id`,
|
- the library retains the loaded manifest data, `title`, `app_id`,
|
||||||
`app_version`, the internal cartridge path, and discovery metadata;
|
`app_version`, the internal cartridge path, and discovery metadata;
|
||||||
|
- the library entry identity is the input to the SystemOS Game switch target;
|
||||||
|
- `app_id` is the v1 identity used to distinguish same-Game resume from
|
||||||
|
different-Game destructive replacement;
|
||||||
- invalid candidates are logged or reported as diagnostics and omitted from the
|
- invalid candidates are logged or reported as diagnostics and omitted from the
|
||||||
Home list;
|
Home list;
|
||||||
- valid non-Game cartridges are omitted from the Game library.
|
- valid non-Game cartridges are omitted from the Game library.
|
||||||
@@ -193,6 +196,11 @@ For the v1 Home games library:
|
|||||||
Discovery reads metadata for cataloging. It does not replace the normal
|
Discovery reads metadata for cataloging. It does not replace the normal
|
||||||
cartridge loader used when firmware starts the selected cartridge.
|
cartridge loader used when firmware starts the selected cartridge.
|
||||||
|
|
||||||
|
Selecting a discovered Game from Home is not cartridge self-execution and is not
|
||||||
|
guest-controlled. The cartridge path is consumed by firmware/SystemOS, which
|
||||||
|
owns same-Game resume, different-Game replacement, failure recovery, and VM
|
||||||
|
session creation policy.
|
||||||
|
|
||||||
### Packaged `.pmc` form
|
### Packaged `.pmc` form
|
||||||
|
|
||||||
This form is recognized conceptually by the loader boundary, but its actual load path is not implemented yet.
|
This form is recognized conceptually by the loader boundary, but its actual load path is not implemented yet.
|
||||||
|
|||||||
@@ -97,9 +97,11 @@ The v1 games root contract is:
|
|||||||
and transitions through `LoadCartridge`;
|
and transitions through `LoadCartridge`;
|
||||||
- launch failure leaves or returns the machine to Home and records an error.
|
- launch failure leaves or returns the machine to Home and records an error.
|
||||||
|
|
||||||
Game-to-game switching after a game is already active is not part of this boot
|
Game-to-game switching after a game is already active is not a boot profile.
|
||||||
profile. That orchestration belongs to the foreground/home and cartridge switch
|
That orchestration belongs to the foreground/home and cartridge switch
|
||||||
contracts.
|
contracts. In that path, SystemOS owns the switch policy: selecting the same
|
||||||
|
resident Game resumes it, while selecting a different Game performs destructive
|
||||||
|
replacement and creates a fresh VM session for the new Game.
|
||||||
|
|
||||||
The foreground/home contract defines `Game -> Home/Shell -> same Game` after a
|
The foreground/home contract defines `Game -> Home/Shell -> same Game` after a
|
||||||
Game is already running. It does not change direct `--run`, debugger direct
|
Game is already running. It does not change direct `--run`, debugger direct
|
||||||
@@ -108,6 +110,10 @@ are host/system controls, not guest cartridge boot APIs.
|
|||||||
|
|
||||||
Direct boot creates the initial VM session for the selected cartridge. It does
|
Direct boot creates the initial VM session for the selected cartridge. It does
|
||||||
not create a reusable global VM shared by later Game or Shell cartridges.
|
not create a reusable global VM shared by later Game or Shell cartridges.
|
||||||
|
Direct boot and debug boot MUST NOT be treated as failed-switch recovery paths:
|
||||||
|
load or initialization failures for direct boot may transition to the crash
|
||||||
|
flow, while Home-driven switch failures return to Home and do not restore the
|
||||||
|
previous Game.
|
||||||
|
|
||||||
## 5 Firmware State Relationship
|
## 5 Firmware State Relationship
|
||||||
|
|
||||||
@@ -152,6 +158,10 @@ Direct single-cartridge boot remains a separate validation path:
|
|||||||
cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console
|
cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Game switch validation should cover the Home-driven two-cartridge path, for
|
||||||
|
example `Stress Console -> Home -> Dummy Boy`, and assert that the first Game is
|
||||||
|
not resumable after replacement.
|
||||||
|
|
||||||
## 8 Relationship to Other Specs
|
## 8 Relationship to Other Specs
|
||||||
|
|
||||||
- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines the firmware state machine that consumes boot targets.
|
- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines the firmware state machine that consumes boot targets.
|
||||||
|
|||||||
@@ -115,7 +115,7 @@ For `BankType::GLYPH`, the v1 runtime-facing contract is:
|
|||||||
- `codec = NONE`
|
- `codec = NONE`
|
||||||
- serialized pixels use packed `u4` palette indices
|
- serialized pixels use packed `u4` palette indices
|
||||||
- serialized palettes use `RGBA8888` with canonical RGBA channel order
|
- serialized palettes use `RGBA8888` with canonical RGBA channel order
|
||||||
- `palette_count = 64`
|
- `palette_count` is the number of serialized and resident palettes and must be in `1..=64`
|
||||||
- runtime materialization may expand pixel indices to one `u8` per pixel
|
- runtime materialization may expand pixel indices to one `u8` per pixel
|
||||||
|
|
||||||
For `GLYPH`, `NONE` means there is no additional generic codec layer beyond the bank contract itself.
|
For `GLYPH`, `NONE` means there is no additional generic codec layer beyond the bank contract itself.
|
||||||
@@ -136,7 +136,7 @@ Required effective metadata fields for `GLYPH` at the root level:
|
|||||||
- `tile_size`: tile edge in pixels; valid values are `8`, `16`, or `32`
|
- `tile_size`: tile edge in pixels; valid values are `8`, `16`, or `32`
|
||||||
- `width`: total sheet width in pixels
|
- `width`: total sheet width in pixels
|
||||||
- `height`: total sheet height in pixels
|
- `height`: total sheet height in pixels
|
||||||
- `palette_count`: number of serialized palettes for the bank
|
- `palette_count`: number of serialized palettes and resident runtime palettes for the bank
|
||||||
|
|
||||||
Optional informative subtrees:
|
Optional informative subtrees:
|
||||||
|
|
||||||
@@ -145,7 +145,7 @@ Optional informative subtrees:
|
|||||||
|
|
||||||
Validation rules for `GLYPH` v1:
|
Validation rules for `GLYPH` v1:
|
||||||
|
|
||||||
- `palette_count` must be `64`
|
- `palette_count` must be in the inclusive range `1..=64`
|
||||||
- `width * height` defines the number of logical indexed pixels in the decoded sheet
|
- `width * height` defines the number of logical indexed pixels in the decoded sheet
|
||||||
- extra metadata may exist, but the runtime contract must not depend on it to reconstruct the in-memory bank unless that data is defined at the root as an effective field.
|
- extra metadata may exist, but the runtime contract must not depend on it to reconstruct the in-memory bank unless that data is defined at the root as an effective field.
|
||||||
|
|
||||||
@@ -158,7 +158,16 @@ The tile-bank payload therefore separates serialized storage form from runtime m
|
|||||||
|
|
||||||
- serialized pixel plane: packed `4bpp`
|
- serialized pixel plane: packed `4bpp`
|
||||||
- decoded pixel plane: expanded `u8` indices, one entry per pixel
|
- decoded pixel plane: expanded `u8` indices, one entry per pixel
|
||||||
- palette table: `64 * 16` colors in RGBA8888 channel order
|
- palette table: `palette_count * 16` colors in RGBA8888 channel order
|
||||||
|
|
||||||
|
For `GLYPH` v1:
|
||||||
|
|
||||||
|
```text
|
||||||
|
serialized_pixel_bytes = ceil(width * height / 2)
|
||||||
|
palette_bytes = palette_count * 16 * 4
|
||||||
|
size = serialized_pixel_bytes + palette_bytes
|
||||||
|
decoded_size = (width * height) + palette_bytes
|
||||||
|
```
|
||||||
|
|
||||||
For `GLYPH` v1:
|
For `GLYPH` v1:
|
||||||
|
|
||||||
@@ -172,6 +181,11 @@ before they are loaded by the runtime.
|
|||||||
Palette indices are ordinary indices. Transparency is represented by the alpha
|
Palette indices are ordinary indices. Transparency is represented by the alpha
|
||||||
channel of the resolved RGBA8888 palette entry, not by reserving index `0`.
|
channel of the resolved RGBA8888 palette entry, not by reserving index `0`.
|
||||||
|
|
||||||
|
`palette_id` is valid only when it is lower than the referenced resident glyph
|
||||||
|
bank's `palette_count`. Canonical runtime composition MUST NOT substitute
|
||||||
|
transparent, black, or any other default color for `palette_id >=
|
||||||
|
palette_count`.
|
||||||
|
|
||||||
### 4.2 `SCENE` asset contract in v1
|
### 4.2 `SCENE` asset contract in v1
|
||||||
|
|
||||||
For `BankType::SCENE`, the v1 runtime-facing contract is:
|
For `BankType::SCENE`, the v1 runtime-facing contract is:
|
||||||
|
|||||||
@@ -65,6 +65,12 @@ dedicated `System` profile ABI and stdlib/framework.
|
|||||||
|
|
||||||
## 3 Syscall Resolution
|
## 3 Syscall Resolution
|
||||||
|
|
||||||
|
PBX, Prometeu Bytecode Executable, is the runtime executable bytecode format.
|
||||||
|
Its canonical file magic is `PBX\0`. The former PBS-prefixed magic is not valid
|
||||||
|
for PBX artifacts: PBS names a frontend language, while PBX names the executable
|
||||||
|
artifact accepted by the runtime. This distinction is required because Prometeu
|
||||||
|
bytecode can be produced by multiple frontends.
|
||||||
|
|
||||||
The host maintains a registry:
|
The host maintains a registry:
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|||||||
@@ -0,0 +1,11 @@
|
|||||||
|
# Dummy Boy
|
||||||
|
|
||||||
|
Regenerate this cartridge with:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
cargo run -p pbxgen-dummy-boy
|
||||||
|
```
|
||||||
|
|
||||||
|
Dummy Boy is a minimal visual Game cartridge used by runtime switch tests. It
|
||||||
|
clears the frame and draws a centered square whose fill color cycles
|
||||||
|
deterministically across frames.
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"magic": "PMTU",
|
||||||
|
"cartridge_version": 1,
|
||||||
|
"app_id": 2,
|
||||||
|
"title": "Dummy Boy",
|
||||||
|
"app_version": "0.1.0",
|
||||||
|
"app_mode": "Game",
|
||||||
|
"capabilities": ["gfx2d"]
|
||||||
|
}
|
||||||
Binary file not shown.
Binary file not shown.
Reference in New Issue
Block a user