From ee39ad4f477c0f4bf3276023101885d383aa467f Mon Sep 17 00:00:00 2001 From: SirEdvin Date: Thu, 16 Jul 2026 09:03:08 +0000 Subject: [PATCH 1/2] docs: add player-focused peripheral pages --- .../documentation/guides/advanced-items.md | 20 +- .../documentation/guides/basic-digitizer.md | 27 ++- .../documentation/index.md | 35 ++- .../documentation/theme/digitalitems.css | 215 +++++++++++++++++- 4 files changed, 272 insertions(+), 25 deletions(-) diff --git a/projects/typed-peripheral-digitalitems/documentation/guides/advanced-items.md b/projects/typed-peripheral-digitalitems/documentation/guides/advanced-items.md index f245942..ab3d3d3 100644 --- a/projects/typed-peripheral-digitalitems/documentation/guides/advanced-items.md +++ b/projects/typed-peripheral-digitalitems/documentation/guides/advanced-items.md @@ -1,9 +1,27 @@ -# Advanced Items +# Advanced Digitizer + +
+
Advanced digitizer block
+
MULTI-STORAGE PERIPHERAL

The advanced digitizer moves items, fluids, and energy between attached storage and durable digital identifiers.

Peripheral type
advanced_digitizer
Storage
Items, fluids, energy
Failure style
Recoverable result pairs
+
+ +## At a glance + +| Method | Returns | What it does | +| --- | --- | --- | +| `digitize(mode, source?, filter?, limit?, destination?)` | `id, error` | Extracts content and creates or extends an ID. | +| `rematerialize(mode, id, limit?, destination?)` | `amount, error` | Inserts stored content into a destination. | +| `get(mode, id)` | ID information or `nil` | Inspects current contents and decay metadata. | +| `refresh(mode, id)` | Boolean | Refreshes an ID if it still exists. | +| `getConfiguration()` | Configuration table | Reports decay and per-mode stack limits. | The advanced digitizer can extract from its internal inventory with source `self`, or from an attached inventory/item storage by peripheral name. The source defaults to `self`. +> **Mode matters:** an identifier belongs to exactly one of `item`, `fluid`, or +> `energy`. Always use the same mode when inspecting, refreshing, or restoring it. + Item filters may be: - A one-based slot number. This requires slotted storage. diff --git a/projects/typed-peripheral-digitalitems/documentation/guides/basic-digitizer.md b/projects/typed-peripheral-digitalitems/documentation/guides/basic-digitizer.md index 8ce2709..98b6786 100644 --- a/projects/typed-peripheral-digitalitems/documentation/guides/basic-digitizer.md +++ b/projects/typed-peripheral-digitalitems/documentation/guides/basic-digitizer.md @@ -1,8 +1,27 @@ # Basic Digitizer -The basic digitizer handles items in its own inventory. Slots are one-based and -default to slot 1. `digitize()` removes the complete stack; `digitizeAmount()` -requires an exact positive amount no greater than the physical stack. +
+
Digitizer block
+
ITEM PERIPHERAL

The basic digitizer turns physical item stacks into portable digital identifiers and restores them through its internal inventory.

Peripheral type
digitizer
Storage
Items
Failure style
Lua errors
+
+ +## At a glance + +| Method | Returns | What it does | +| --- | --- | --- | +| `digitize(slot?)` | Digital ID | Digitizes the complete stack in a slot. | +| `digitizeAmount(amount, slot?)` | Digital ID | Digitizes an exact number of items. | +| `rematerialize(id)` | Item count | Restores as much of an ID as the inventory accepts. | +| `rematerializeAmount(id, amount)` | Item count | Requests an exact portion of an ID. | +| `getIDInfo(id)` | Item and timing data | Inspects the contents and decay deadline. | +| `refresh(id)` | Nothing | Resets the identifier's decay deadline. | + +Slots are one-based and default to slot 1. `digitize()` removes the complete +stack; `digitizeAmount()` requires an exact positive amount no greater than the +physical stack. + +> **Inherited inventory API:** `size`, `list`, `getItemDetail`, `getItemLimit`, +> `pushItems`, and `pullItems` are also available on this peripheral. ## Round trip a partial stack @@ -29,6 +48,8 @@ local inserted = digitizer.rematerializeAmount(id, 8) print("Inserted " .. inserted) ``` +## Errors and remaining items + All failures throw. Empty slots, non-positive amounts, requesting more than the physical or digital count, and unknown or decayed identifiers are errors. diff --git a/projects/typed-peripheral-digitalitems/documentation/index.md b/projects/typed-peripheral-digitalitems/documentation/index.md index e992658..c3dd707 100644 --- a/projects/typed-peripheral-digitalitems/documentation/index.md +++ b/projects/typed-peripheral-digitalitems/documentation/index.md @@ -1,16 +1,27 @@ -# Digital Items Typed Peripheral API +# Digital Items Peripheral Manual -This package supplies TypeScriptToLua declarations and peripheral providers for -Digital Items 3. It covers the item-only `digitizer` and the multi-storage -`advanced_digitizer` peripherals. +Player-focused documentation and typed APIs for the Digital Items 3 peripherals. +Use these pages whether you write programs directly in CraftOS Lua or compile +TypeScript with TypeScriptToLua. -## Choose a peripheral +## Choose your digitizer -- Use the basic digitizer for simple item workflows through its internal inventory. -- Use the advanced digitizer to address remote item, fluid, or energy storage, merge content into existing identifiers, and handle recoverable failures. -- Both peripherals inherit inventory methods. The advanced digitizer additionally reports decay and stack limits through `getConfiguration()`. +
+ + Digitizer block + DigitizerPeripheral type: digitizerDigitize and restore items through a simple internal inventory.Open peripheral guide → + + + Advanced digitizer block + Advanced DigitizerPeripheral type: advanced_digitizerMove items, fluids, and energy between remote storage and digital IDs.Open peripheral guide → + +
-## Documentation +Both peripherals include the standard CC:Tweaked inventory methods. The advanced +digitizer also exposes configured decay and storage limits through +`getConfiguration()`. + +## Start here - [Getting started](getting-started.md) - [Digital identifiers](digital-identifiers.md) @@ -18,6 +29,6 @@ Digital Items 3. It covers the item-only `digitizer` and the multi-storage - [Advanced item guide](guides/advanced-items.md) - [Fluid and energy guide](guides/fluids-and-energy.md) -The generated API reference documents every exported type, method overload, and -provider. Guide examples are shown first in TypeScriptToLua and then in direct -CraftOS Lua. +The **Guides** explain behavior in player terms and include both Lua and +TypeScript examples. The **API reference** is the precise source for signatures, +overloads, return types, and provider declarations. diff --git a/projects/typed-peripheral-digitalitems/documentation/theme/digitalitems.css b/projects/typed-peripheral-digitalitems/documentation/theme/digitalitems.css index 604ba7f..66d552d 100644 --- a/projects/typed-peripheral-digitalitems/documentation/theme/digitalitems.css +++ b/projects/typed-peripheral-digitalitems/documentation/theme/digitalitems.css @@ -1,7 +1,7 @@ :root { - --di-ink: #071116; - --di-panel: #0c1c23; - --di-panel-raised: #102832; + --di-ink: #10191d; + --di-panel: #16252b; + --di-panel-raised: #1c3038; --di-grid: rgba(75, 225, 210, 0.08); --di-cyan: #4be1d2; --di-cyan-soft: #a0fff4; @@ -37,7 +37,9 @@ body { linear-gradient(90deg, var(--di-grid) 1px, transparent 1px), radial-gradient(circle at 83% 9%, rgba(75, 225, 210, 0.11), transparent 28rem); background-size: 48px 48px, 48px 48px, auto; - font-family: "Trebuchet MS", "Gill Sans", sans-serif; + font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; + font-size: 16px; + line-height: 1.7; } .di-signal-line { @@ -57,12 +59,13 @@ body { .col-content { position: relative; + max-width: 920px; } .col-content::before { content: "DIGITAL ITEMS // PERIPHERAL ARCHIVE"; display: block; - margin: 1.5rem 0 2rem; + margin: 1.25rem 0 1.5rem; color: var(--di-cyan); font: 700 0.72rem/1.2 "Lucida Console", Monaco, monospace; letter-spacing: 0.16em; @@ -74,17 +77,20 @@ h3, h4, .site-menu, .tsd-page-title { - font-family: "Lucida Console", Monaco, monospace; - letter-spacing: -0.035em; + font-family: Inter, ui-sans-serif, system-ui, sans-serif; + letter-spacing: -0.025em; } h1 { text-wrap: balance; + font-size: clamp(2rem, 5vw, 3rem); + line-height: 1.12; } h2 { border-bottom: 1px solid color-mix(in srgb, var(--di-cyan) 28%, transparent); padding-bottom: 0.55rem; + margin-top: 2.4rem; } .tsd-panel, @@ -92,8 +98,8 @@ h2 { pre, table { border: 1px solid color-mix(in srgb, var(--di-cyan) 18%, transparent); - border-radius: 4px; - box-shadow: 6px 6px 0 rgba(0, 0, 0, 0.14); + border-radius: 8px; + box-shadow: 0 10px 28px rgba(0, 0, 0, 0.12); } .tsd-signature, @@ -110,6 +116,167 @@ a:hover { color: var(--di-amber); } +.col-content p, +.col-content li { + max-width: 78ch; +} + +.col-content table { + width: 100%; + border-collapse: collapse; + overflow: hidden; +} + +.col-content th { + color: var(--di-cyan-soft); + background: var(--di-panel-raised); + text-align: left; +} + +.col-content th, +.col-content td { + padding: 0.8rem 1rem; + border-bottom: 1px solid color-mix(in srgb, var(--di-cyan) 14%, transparent); + vertical-align: top; +} + +.col-content blockquote { + margin: 1.5rem 0; + padding: 0.8rem 1.1rem; + border-left: 4px solid var(--di-amber); + background: color-mix(in srgb, var(--di-amber) 7%, var(--di-panel)); +} + +.col-content blockquote p { + margin: 0; +} + +.di-peripheral-grid { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: 1rem; + margin: 1.5rem 0 2rem; +} + +.di-peripheral-card, +.di-peripheral-hero { + border: 1px solid color-mix(in srgb, var(--di-cyan) 32%, transparent); + background: linear-gradient(145deg, var(--di-panel-raised), var(--di-panel)); +} + +.di-peripheral-card { + display: flex; + gap: 1.2rem; + min-height: 190px; + padding: 1.25rem; + border-radius: 10px; + color: var(--color-text); + text-decoration: none; + transition: border-color 160ms ease, transform 160ms ease; +} + +.di-peripheral-card:hover { + border-color: var(--di-cyan); + color: var(--color-text); + transform: translateY(-3px); +} + +.di-peripheral-card--advanced, +.di-peripheral-hero--advanced { + border-color: color-mix(in srgb, var(--di-amber) 35%, transparent); +} + +.di-peripheral-image { + display: grid; + flex: 0 0 128px; + min-height: 128px; + place-items: center; + border-radius: 6px; + background-color: #0a1114; + background-image: linear-gradient(45deg, rgba(255,255,255,.035) 25%, transparent 25%, transparent 75%, rgba(255,255,255,.035) 75%), linear-gradient(45deg, rgba(255,255,255,.035) 25%, transparent 25%, transparent 75%, rgba(255,255,255,.035) 75%); + background-position: 0 0, 8px 8px; + background-size: 16px 16px; +} + +.di-peripheral-image img { + width: 112px; + height: 112px; + image-rendering: pixelated; +} + +.di-peripheral-copy { + display: flex; + flex-direction: column; +} + +.di-peripheral-copy strong { + font-size: 1.25rem; +} + +.di-peripheral-copy small { + margin: 0.25rem 0 0.75rem; + color: var(--di-muted); +} + +.di-peripheral-copy b { + margin-top: auto; + color: var(--di-cyan); + font-size: 0.82rem; +} + +.di-peripheral-hero { + display: grid; + grid-template-columns: 176px minmax(0, 1fr); + gap: 1.75rem; + margin: 1rem 0 2rem; + padding: 1.5rem; + border-radius: 10px; +} + +.di-peripheral-hero .di-peripheral-image { + min-height: 176px; +} + +.di-peripheral-hero .di-peripheral-image img { + width: 144px; + height: 144px; +} + +.di-eyebrow { + color: var(--di-amber); + font: 700 0.7rem/1 "Lucida Console", Monaco, monospace; + letter-spacing: 0.12em; +} + +.di-peripheral-hero p { + margin: 0.55rem 0 1rem; + font-size: 1.05rem; +} + +.di-peripheral-hero dl { + display: grid; + grid-template-columns: repeat(3, minmax(0, 1fr)); + gap: 0.7rem; + margin: 0; +} + +.di-peripheral-hero dl div { + min-width: 0; +} + +.di-peripheral-hero dt { + color: var(--di-muted); + font-size: 0.68rem; + text-transform: uppercase; + letter-spacing: 0.06em; +} + +.di-peripheral-hero dd { + margin: 0.2rem 0 0; + overflow-wrap: anywhere; + font-weight: 650; +} + .di-version-panel { margin: 0.75rem 0 1.35rem; padding: 0.8rem; @@ -152,6 +319,36 @@ a:hover { max-width: 100%; overflow-x: auto; } + + .di-peripheral-grid { + grid-template-columns: 1fr; + } + + .di-peripheral-hero { + grid-template-columns: 1fr; + } + + .di-peripheral-hero .di-peripheral-image { + min-height: 144px; + } + + .di-peripheral-hero dl { + grid-template-columns: 1fr 1fr; + } +} + +@media (max-width: 480px) { + .di-peripheral-card { + flex-direction: column; + } + + .di-peripheral-image { + flex-basis: auto; + } + + .di-peripheral-hero dl { + grid-template-columns: 1fr; + } } @media (prefers-reduced-motion: no-preference) { From 7300a06886017ee6b029cfeda14681515c982937 Mon Sep 17 00:00:00 2001 From: SirEdvin Date: Thu, 16 Jul 2026 09:08:10 +0000 Subject: [PATCH 2/2] docs: generate peripheral method reference --- .../documentation/guides/advanced-items.md | 14 ++--- .../documentation/guides/basic-digitizer.md | 15 ++--- .../documentation/theme/digitalitems.css | 55 +++++++++++++++++++ .../documentation/theme/plugin.mjs | 53 +++++++++++++++++- 4 files changed, 115 insertions(+), 22 deletions(-) diff --git a/projects/typed-peripheral-digitalitems/documentation/guides/advanced-items.md b/projects/typed-peripheral-digitalitems/documentation/guides/advanced-items.md index ab3d3d3..42faf03 100644 --- a/projects/typed-peripheral-digitalitems/documentation/guides/advanced-items.md +++ b/projects/typed-peripheral-digitalitems/documentation/guides/advanced-items.md @@ -1,3 +1,7 @@ +--- +peripheralInterface: AdvancedDigitizer +--- + # Advanced Digitizer
@@ -5,16 +9,6 @@
MULTI-STORAGE PERIPHERAL

The advanced digitizer moves items, fluids, and energy between attached storage and durable digital identifiers.

Peripheral type
advanced_digitizer
Storage
Items, fluids, energy
Failure style
Recoverable result pairs
-## At a glance - -| Method | Returns | What it does | -| --- | --- | --- | -| `digitize(mode, source?, filter?, limit?, destination?)` | `id, error` | Extracts content and creates or extends an ID. | -| `rematerialize(mode, id, limit?, destination?)` | `amount, error` | Inserts stored content into a destination. | -| `get(mode, id)` | ID information or `nil` | Inspects current contents and decay metadata. | -| `refresh(mode, id)` | Boolean | Refreshes an ID if it still exists. | -| `getConfiguration()` | Configuration table | Reports decay and per-mode stack limits. | - The advanced digitizer can extract from its internal inventory with source `self`, or from an attached inventory/item storage by peripheral name. The source defaults to `self`. diff --git a/projects/typed-peripheral-digitalitems/documentation/guides/basic-digitizer.md b/projects/typed-peripheral-digitalitems/documentation/guides/basic-digitizer.md index 98b6786..b3eb5c6 100644 --- a/projects/typed-peripheral-digitalitems/documentation/guides/basic-digitizer.md +++ b/projects/typed-peripheral-digitalitems/documentation/guides/basic-digitizer.md @@ -1,3 +1,7 @@ +--- +peripheralInterface: Digitizer +--- + # Basic Digitizer
@@ -5,17 +9,6 @@
ITEM PERIPHERAL

The basic digitizer turns physical item stacks into portable digital identifiers and restores them through its internal inventory.

Peripheral type
digitizer
Storage
Items
Failure style
Lua errors
-## At a glance - -| Method | Returns | What it does | -| --- | --- | --- | -| `digitize(slot?)` | Digital ID | Digitizes the complete stack in a slot. | -| `digitizeAmount(amount, slot?)` | Digital ID | Digitizes an exact number of items. | -| `rematerialize(id)` | Item count | Restores as much of an ID as the inventory accepts. | -| `rematerializeAmount(id, amount)` | Item count | Requests an exact portion of an ID. | -| `getIDInfo(id)` | Item and timing data | Inspects the contents and decay deadline. | -| `refresh(id)` | Nothing | Resets the identifier's decay deadline. | - Slots are one-based and default to slot 1. `digitize()` removes the complete stack; `digitizeAmount()` requires an exact positive amount no greater than the physical stack. diff --git a/projects/typed-peripheral-digitalitems/documentation/theme/digitalitems.css b/projects/typed-peripheral-digitalitems/documentation/theme/digitalitems.css index 66d552d..8b44687 100644 --- a/projects/typed-peripheral-digitalitems/documentation/theme/digitalitems.css +++ b/projects/typed-peripheral-digitalitems/documentation/theme/digitalitems.css @@ -277,6 +277,61 @@ a:hover { font-weight: 650; } +.di-method-reference { + margin-top: 3rem; +} + +.di-generated-note { + margin-bottom: 1.25rem; + color: var(--di-muted); + font-size: 0.9rem; +} + +.di-method-card { + margin: 1rem 0; + border: 1px solid color-mix(in srgb, var(--di-cyan) 24%, transparent); + border-radius: 8px; + background: var(--di-panel); + box-shadow: 0 8px 22px rgba(0, 0, 0, 0.1); + overflow: hidden; +} + +.di-method-card > h3 { + margin: 0; + padding: 0.75rem 1rem; + border-bottom: 1px solid color-mix(in srgb, var(--di-cyan) 18%, transparent); + background: var(--di-panel-raised); + color: var(--di-cyan-soft); + font-size: 1rem; +} + +.di-method-overload { + padding: 1rem; +} + +.di-method-overload + .di-method-overload { + border-top: 1px dashed color-mix(in srgb, var(--di-cyan) 28%, transparent); +} + +.di-method-overload .tsd-signature { + margin: 0 0 1rem; + padding: 0.8rem; + box-shadow: none; + overflow-x: auto; +} + +.di-method-overload .tsd-comment { + margin: 0.75rem 0; +} + +.di-method-overload h4 { + margin: 1rem 0 0.35rem; + color: var(--di-muted); + font-size: 0.78rem; + letter-spacing: 0.05em; + text-transform: uppercase; +} + .di-version-panel { margin: 0.75rem 0 1.35rem; padding: 0.8rem; diff --git a/projects/typed-peripheral-digitalitems/documentation/theme/plugin.mjs b/projects/typed-peripheral-digitalitems/documentation/theme/plugin.mjs index 1c7e274..d4d7dd3 100644 --- a/projects/typed-peripheral-digitalitems/documentation/theme/plugin.mjs +++ b/projects/typed-peripheral-digitalitems/documentation/theme/plugin.mjs @@ -1,4 +1,53 @@ -import { JSX } from "typedoc"; +import { JSX, ReflectionKind } from "typedoc"; + +function renderPeripheralMethods(context) { + if (!context.model.isDocument()) return; + + const interfaceName = context.model.frontmatter.peripheralInterface; + if (typeof interfaceName !== "string") return; + + const peripheral = context.page.project + .getReflectionsByKind(ReflectionKind.Interface) + .find((reflection) => reflection.name === interfaceName); + if (!peripheral?.children) return; + + const methods = peripheral.children.filter( + (reflection) => reflection.kindOf(ReflectionKind.Method) && reflection.signatures?.length + ); + if (methods.length === 0) return; + + context.page.pageHeadings.push({ + link: "#peripheral-methods", + text: "Peripheral methods", + level: 2, + }); + + return JSX.createElement( + "section", + { class: "di-method-reference", "aria-labelledby": "peripheral-methods" }, + JSX.createElement("h2", { id: "peripheral-methods" }, "Peripheral methods"), + JSX.createElement( + "p", + { class: "di-generated-note" }, + "Generated from the TypeScript interface. Signatures, parameters, return values, and errors stay synchronized with the published API." + ), + ...methods.map((method) => + JSX.createElement( + "article", + { class: "di-method-card" }, + JSX.createElement("h3", null, method.name), + ...method.signatures.map((signature) => + JSX.createElement( + "div", + { class: "di-method-overload" }, + context.memberSignatureTitle(signature), + context.memberSignatureBody(signature, { hideSources: true }) + ) + ) + ) + ) + ); +} export function load(app) { app.renderer.hooks.on("body.begin", () => @@ -20,4 +69,6 @@ export function load(app) { ) ) ); + + app.renderer.hooks.on("content.end", renderPeripheralMethods); }