fixes on colors and dist
This commit is contained in:
@@ -0,0 +1,83 @@
|
||||
# Prometeu DevTools Protocol
|
||||
|
||||
This document describes the communication protocol between the Prometeu Runtime and development tools (such as the Prometeu Debugger).
|
||||
|
||||
## Overview
|
||||
|
||||
The protocol is based on JSON, sent via a transport connection (usually TCP). Each message is a JSON object on a single line (JSONL).
|
||||
|
||||
## Structure
|
||||
|
||||
- **[protocol.json](protocol.json)**: Formal definition of the protocol in JSON format.
|
||||
- **[protocol.md](README.md)**: Human-readable documentation describing commands, events, and types.
|
||||
- **[examples/](examples)**: Examples of message flows (handshake, breakpoints, etc.) in JSONL format.
|
||||
|
||||
## Versioning
|
||||
|
||||
The protocol has an explicit version defined in the `protocol_version` field.
|
||||
|
||||
- Incompatible changes (breaking changes) increment the major version.
|
||||
- New fields in existing messages should be optional whenever possible to maintain backward compatibility.
|
||||
|
||||
The current protocol version is: **1**
|
||||
|
||||
## Handshake
|
||||
|
||||
Upon connecting, the Runtime sends a handshake message to the client.
|
||||
|
||||
### Runtime -> Client
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "handshake",
|
||||
"protocol_version": 1,
|
||||
"runtime_version": "0.1.0",
|
||||
"cartridge": {
|
||||
"app_id": 1,
|
||||
"title": "ColorSquare",
|
||||
"app_version": "1.0.0",
|
||||
"app_mode": "Debug"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Client -> Runtime
|
||||
|
||||
The client must respond with `start` or `ok` to start the session.
|
||||
|
||||
```json
|
||||
{ "type": "start" }
|
||||
```
|
||||
|
||||
## Requests
|
||||
|
||||
The client can send the following requests to control execution:
|
||||
|
||||
| Name | Parameters | Description |
|
||||
|------|------------|-----------|
|
||||
| `pause` | `[]` | Pauses VM execution. |
|
||||
| `resume` | `[]` | Resumes VM execution. |
|
||||
| `step` | `[]` | Executes a single instruction (PC). |
|
||||
| `stepFrame` | `[]` | Executes until the next frame. |
|
||||
| `getState` | `[]` | Returns the current VM state (`pc`, `stack_top`, `frame_index`, `app_id`). |
|
||||
| `setBreakpoint` | `{"pc": number}` | Sets a breakpoint at the specified address. |
|
||||
| `clearBreakpoint` | `{"pc": number}` | Removes a breakpoint at the specified address. |
|
||||
|
||||
## Responses
|
||||
|
||||
Some requests generate specific responses. For example, `getState` returns the VM state.
|
||||
|
||||
## Events
|
||||
|
||||
The Runtime can send asynchronous events to the client:
|
||||
|
||||
| Name | Fields | Description |
|
||||
|------|--------|-----------|
|
||||
| `breakpointHit` | `pc`, `frame_index` | Emitted when execution hits a breakpoint. |
|
||||
| `log` | `level`, `source`, `msg` | Emitted when the running code generates a log. |
|
||||
| `telemetry` | `frame_index`, `vm_steps`, `syscalls`, `cycles` | Execution statistics sent periodically. |
|
||||
| `cert` | `rule`, `used`, `limit`, `frame_index` | Certification information and resource limits. |
|
||||
|
||||
## Examples
|
||||
|
||||
See the `examples/` folder for complete message flows.
|
||||
@@ -0,0 +1,4 @@
|
||||
{"type":"start"}
|
||||
{"type":"pause"}
|
||||
{"type":"getState"}
|
||||
{"type":"resume"}
|
||||
@@ -0,0 +1,2 @@
|
||||
{"type":"setBreakpoint","pc":120}
|
||||
{"event":"breakpointHit","pc":120,"frame_index":10}
|
||||
@@ -0,0 +1,2 @@
|
||||
{"type":"handshake","protocol_version":1,"runtime_version":"0.1","cartridge":{"app_id":1,"title":"ColorSquare","app_version":"1.0.0","app_mode":"Debug"}}
|
||||
{"type":"start"}
|
||||
@@ -0,0 +1,61 @@
|
||||
{
|
||||
"protocol_version": 1,
|
||||
"handshake": {
|
||||
"runtime_to_client": {
|
||||
"type": "handshake",
|
||||
"fields": ["protocol_version", "runtime_version", "cartridge"]
|
||||
},
|
||||
"client_to_runtime": {
|
||||
"type": "start|ok"
|
||||
}
|
||||
},
|
||||
"requests": [
|
||||
{
|
||||
"type": "pause",
|
||||
"params": []
|
||||
},
|
||||
{
|
||||
"type": "resume",
|
||||
"params": []
|
||||
},
|
||||
{
|
||||
"type": "step",
|
||||
"params": []
|
||||
},
|
||||
{
|
||||
"type": "stepFrame",
|
||||
"params": []
|
||||
},
|
||||
{
|
||||
"type": "getState",
|
||||
"params": [],
|
||||
"response": ["pc", "stack_top", "frame_index", "app_id"]
|
||||
},
|
||||
{
|
||||
"type": "setBreakpoint",
|
||||
"params": ["pc"]
|
||||
},
|
||||
{
|
||||
"type": "clearBreakpoint",
|
||||
"params": ["pc"]
|
||||
}
|
||||
],
|
||||
"events": [
|
||||
{
|
||||
"event": "breakpointHit",
|
||||
"fields": ["pc", "frame_index"]
|
||||
},
|
||||
{
|
||||
"event": "log",
|
||||
"fields": ["level", "source", "msg"]
|
||||
},
|
||||
{
|
||||
"event": "telemetry",
|
||||
"fields": ["frame_index", "vm_steps", "syscalls", "cycles"]
|
||||
},
|
||||
{
|
||||
"event": "cert",
|
||||
"fields": ["rule", "used", "limit", "frame_index"]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"name": "@prometeu/sdk",
|
||||
"version": "0.1.0",
|
||||
"main": "src/index.ts",
|
||||
"types": "types/index.d.ts"
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
export const Audio = audio;
|
||||
export type Audio = Prometeu.Audio;
|
||||
@@ -0,0 +1,25 @@
|
||||
export type Color565 = Prometeu.Color565;
|
||||
|
||||
function clamp8(n: number): number {
|
||||
return n < 0 ? 0 : n > 255 ? 255 : n | 0;
|
||||
}
|
||||
|
||||
export const Color: Prometeu.Color = {
|
||||
black: 0x0000 as Color565,
|
||||
white: 0xffff as Color565,
|
||||
red: 0xf800 as Color565,
|
||||
green: 0x07e0 as Color565,
|
||||
blue: 0x001f as Color565,
|
||||
yellow: 0xffe0 as Color565,
|
||||
cyan: 0x07ff as Color565,
|
||||
magenta: 0xf81f as Color565,
|
||||
indigo: 0x4810 as Color565,
|
||||
|
||||
rgb(r: number, g: number, b: number): Color565 {
|
||||
r = clamp8(r); g = clamp8(g); b = clamp8(b);
|
||||
const r5 = (r >> 3) & 0x1f;
|
||||
const g6 = (g >> 2) & 0x3f;
|
||||
const b5 = (b >> 3) & 0x1f;
|
||||
return ((r5 << 11) | (g6 << 5) | b5) as Color565;
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,2 @@
|
||||
export const Fs = fs;
|
||||
export type Fs = Prometeu.Fs;
|
||||
@@ -0,0 +1 @@
|
||||
export type Gfx = Prometeu.Gfx;
|
||||
@@ -0,0 +1,8 @@
|
||||
export { Color } from "./color";
|
||||
export { Pad, Touch } from "./input";
|
||||
export { Gfx } from "./gfx";
|
||||
export { System } from "./system";
|
||||
export { Audio } from "./audio";
|
||||
export { Fs } from "./fs";
|
||||
export { Log, LogLevel } from "./log";
|
||||
export type { Color565 } from "./color";
|
||||
@@ -0,0 +1,4 @@
|
||||
|
||||
|
||||
export const Pad: Prometeu.Pad = pad;
|
||||
export const Touch: Prometeu.Touch = touch;
|
||||
@@ -0,0 +1,11 @@
|
||||
export const Log = log;
|
||||
export type Log = Prometeu.Log;
|
||||
|
||||
export enum LogLevel {
|
||||
Trace = 0,
|
||||
Debug = 1,
|
||||
Info = 2,
|
||||
Warn = 3,
|
||||
Error = 4,
|
||||
Fatal = 5,
|
||||
}
|
||||
@@ -0,0 +1,2 @@
|
||||
export const System = system;
|
||||
export type System = Prometeu.System;
|
||||
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
}
|
||||
}
|
||||
+91
@@ -0,0 +1,91 @@
|
||||
export {}; // that is a module, should not include any other scope here
|
||||
|
||||
declare global {
|
||||
namespace Prometeu {
|
||||
type Color565 = number & { readonly __brand: "Color565" };
|
||||
|
||||
interface Button {
|
||||
readonly down: boolean;
|
||||
readonly pressed: boolean;
|
||||
readonly released: boolean;
|
||||
readonly holdFrames: number;
|
||||
}
|
||||
|
||||
interface Pad {
|
||||
readonly up: Button;
|
||||
readonly down: Button;
|
||||
readonly left: Button;
|
||||
readonly right: Button;
|
||||
readonly a: Button;
|
||||
readonly b: Button;
|
||||
readonly x: Button;
|
||||
readonly y: Button;
|
||||
readonly l: Button;
|
||||
readonly r: Button;
|
||||
readonly start: Button;
|
||||
readonly select: Button;
|
||||
}
|
||||
|
||||
interface Touch {
|
||||
readonly x: number;
|
||||
readonly y: number;
|
||||
readonly button: Button;
|
||||
}
|
||||
|
||||
interface Gfx {
|
||||
fillRect(x: number, y: number, w: number, h: number, color: Color565): void;
|
||||
drawLine(x1: number, y1: number, x2: number, y2: number, color: Color565): void;
|
||||
drawCircle(x: number, y: number, r: number, color: Color565): void;
|
||||
drawDisc(x: number, y: number, r: number, borderColor: Color565, fillColor: Color565): void;
|
||||
drawSquare(x: number, y: number, w: number, h: number, borderColor: Color565, fillColor: Color565): void;
|
||||
clear(color: Color565): void;
|
||||
}
|
||||
|
||||
interface Color {
|
||||
readonly black: Color565;
|
||||
readonly white: Color565;
|
||||
readonly red: Color565;
|
||||
readonly green: Color565;
|
||||
readonly blue: Color565;
|
||||
readonly yellow: Color565;
|
||||
readonly cyan: Color565;
|
||||
readonly magenta: Color565;
|
||||
readonly indigo: Color565;
|
||||
rgb(r: number, g: number, b: number): Color565;
|
||||
}
|
||||
|
||||
interface System {
|
||||
hasCart(): boolean;
|
||||
}
|
||||
|
||||
interface Audio {
|
||||
playSample(sampleId: number, voiceId: number, volume: number, pan: number, pitch: number): void;
|
||||
}
|
||||
|
||||
interface Fs {
|
||||
open(path: string): number;
|
||||
read(handle: number): string | null;
|
||||
write(handle: number, content: string): boolean;
|
||||
close(handle: number): void;
|
||||
listDir(path: string): string | null;
|
||||
exists(path: string): boolean;
|
||||
delete(path: string): boolean;
|
||||
}
|
||||
|
||||
interface Log {
|
||||
write(level: number, msg: string): void;
|
||||
writeTag(level: number, tag: number, msg: string): void;
|
||||
}
|
||||
}
|
||||
|
||||
export const pad: Prometeu.Pad;
|
||||
export const touch: Prometeu.Touch;
|
||||
export const gfx: Prometeu.Gfx;
|
||||
export const audio: Prometeu.Audio;
|
||||
export const fs: Prometeu.Fs;
|
||||
export const log: Prometeu.Log;
|
||||
export const color: Prometeu.Color;
|
||||
export const system: Prometeu.System;
|
||||
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user