Plethora Bit Starter

https://github.com/zenarenarin/plethora-bit-starter
Admin
A starter repository for building self-contained interactive experiences (bits) that run within the...
Tokens:100,554
Snippets:431
Trust Score:0.8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Background Music Example

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/BIT_BEST_PRACTICES.md

Example of how to play background music using ctx.music, starting it on the first user gesture.

```javascript
let music;
ctx.listen(canvas, 'touchstart', () => {
  music ||= ctx.music.play({ preset: 'ambient', volume: 0.16, fadeInMs: 600 });
}, { once: true });
```

--------------------------------

### AudioContext Initialization Example

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/BIT_BEST_PRACTICES.md

Example of initializing and resuming an AudioContext on the first user gesture.

```javascript
let audioCtx;

ctx.listen(canvas, 'touchstart', () => {
  if (!audioCtx) {
    audioCtx = new AudioContext();
    ctx.onDestroy(() => audioCtx.close());
  }
  audioCtx.resume();
}, { once: true });
```

--------------------------------

### Motion API Usage

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/CLAUDE.md

Examples of starting motion detection and accessing tilt data, requiring the 'motion' permission.

```javascript
ctx.listen(canvas, 'touchstart', () => {
  ctx.motion.start().catch(() => {});
}, { once: true, passive: false });

ctx.raf(() => {
  const x = ctx.motion.tilt.x;
});
```

--------------------------------

### Storage API Usage

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/CLAUDE.md

Examples of using `ctx.storage` to set, get, remove, and clear data, requiring the 'storage' permission.

```javascript
ctx.storage.set('highScore', 42);
const highScore = ctx.storage.get('highScore');
ctx.storage.remove('highScore');
ctx.storage.clear();
```

--------------------------------

### Importing a Module from Plethora Registry

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/CLAUDE.md

Example of importing a module using the resolved Plethora-hosted registry URL.

```javascript
const THREE = await ctx.importModule('https://libs.plethora.studio/three/0.164.1/three.module.js');
```

--------------------------------

### plethora.json Configuration

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/CLAUDE.md

Example `plethora.json` file for a bit, including schema version, runtime, entry point, metadata, and permissions.

```json
{
  "schemaVersion": 1,
  "runtime": "plethora-bit@1",
  "entry": "main.js",
  "title": "My Bit",
  "description": "A tiny interactive scene.",
  "tags": ["creative"],
  "permissions": [],
  "dependencies": []
}
```

--------------------------------

### AudioContext Initialization

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/CLAUDE.md

Example of initializing and resuming an AudioContext for action sounds, requiring the 'audio' permission.

```javascript
let audioCtx;
ctx.listen(canvas, 'touchstart', () => {
  if (!audioCtx) {
    audioCtx = new AudioContext();
    ctx.onDestroy(() => audioCtx.close());
  }
  audioCtx.resume();
}, { once: true });
```

--------------------------------

### Touch Event Handling

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/CLAUDE.md

Example of handling touch events using `ctx.listen`, `changedTouches`, and `preventDefault`.

```javascript
ctx.listen(canvas, 'touchstart', (e) => {
  e.preventDefault();
  ctx.platform.start();
  const t = e.changedTouches[0];
}, { passive: false });
```

--------------------------------

### Declare Permissions

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/BIT_BEST_PRACTICES.md

Example of declaring permissions for a bit package.

```javascript
window.plethoraBit = {
  meta: {
    title: 'Tap Bloom',
    author: 'you',
    description: 'Tap to grow a tiny garden.',
    tags: ['creative'],
    permissions: ['haptics'],
  },
  async init(ctx) {
    ctx.platform.ready();
  },
};
```

--------------------------------

### Importing Registry Libraries

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/BIT_BEST_PRACTICES.md

Example of importing a registry library like Three.js, ensuring secondary files are also loaded from the approved registry.

```javascript
const THREE_URL = 'https://libs.plethora.studio/three/0.164.1/three.module.js';
const THREE = await ctx.importModule(THREE_URL);
```

--------------------------------

### Community Data Examples

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/graphify-out/graph.html

Examples of community data objects, detailing properties like ID, label, color, size, font, title, community ID, community name, source file, file type, and degree.

```json
{
  "id": "enjoy_sunshine_init",
  "label": "init()",
  "color": {"background": "#ffffff", "border": "#E15759"},
  "size": 10.7,
  "font": {"size": 0, "color": "#ffffff"},
  "title": "init()",
  "community": 32,
  "community_name": "Community 32",
  "source_file": "jsgame-bits\\enjoy-sunshine.js",
  "file_type": "code",
  "degree": 1
}
```

```json
{
  "id": "d_scroller_plethora_bit_starter_jsgame_bits_enmeshed_js",
  "label": "enmeshed.js",
  "color": {"background": "#E15759", "border": "#E15759", "highlight": {"background": "#ffffff", "border": "#E15759"}},
  "size": 12.0,
  "font": {"size": 0, "color": "#ffffff"},
  "title": "enmeshed.js",
  "community": 122,
  "community_name": "Community 122",
  "source_file": "jsgame-bits\\enmeshed.js",
  "file_type": "code",
  "degree": 3
}
```

```json
{
  "id": "d_scroller_plethora_bit_starter_jsgame_bits_jump_n_bump_js",
  "label": "jump-n-bump.js",
  "color": {"background": "#76B7B2", "border": "#76B7B2", "highlight": {"background": "#ffffff", "border": "#76B7B2"}},
  "size": 12.0,
  "font": {"size": 0, "color": "#ffffff"},
  "title": "jump-n-bump.js",
  "community": 123,
  "community_name": "Community 123",
  "source_file": "jsgame-bits\\jump-n-bump.js",
  "file_type": "code",
  "degree": 3
}
```

```json
{
  "id": "d_scroller_plethora_bit_starter_jsgame_bits_lost_treasure_js",
  "label": "lost-treasure.js",
  "color": {"background": "#76B7B2", "border": "#76B7B2", "highlight": {"background": "#ffffff", "border": "#76B7B2"}},
  "size": 12.7,
  "font": {"size": 0, "color": "#ffffff"},
  "title": "lost-treasure.js",
  "community": 33,
  "community_name": "Community 33",
  "source_file": "jsgame-bits\\lost-treasure.js",
  "file_type": "code",
  "degree": 4
}
```

--------------------------------

### Context Object Methods

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/CLAUDE.md

Examples of using the `ctx` object for canvas creation, event listening, and scheduling.

```javascript
ctx.width
ctx.height
ctx.dpr
ctx.safeArea
ctx.container

const root = ctx.createRoot(); // DOM UI root, auto-removed
const canvas = ctx.createCanvas2D();
const g = canvas.getContext('2d');

ctx.listen(canvas, 'touchstart', handler, { passive: false });
ctx.raf((dt) => {});
ctx.timeout(cb, ms);
ctx.interval(cb, ms);
ctx.onDestroy(cb);

```

--------------------------------

### Platform Events

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/BIT_BEST_PRACTICES.md

Examples of various platform events that can be triggered within a bit.

```javascript
ctx.platform.ready();                              // required at end of init
ctx.platform.start();                              // first real interaction
ctx.platform.interact({ type: 'tap' });            // each interaction
ctx.platform.setScore(42);                         // games
ctx.platform.setProgress(0.5);                     // progress 0..1
ctx.platform.complete({ score, durationMs });      // natural ending
ctx.platform.fail({ reason: 'hit' });              // game-over
ctx.platform.haptic('light');                      // requires haptics permission
```

--------------------------------

### Login Command

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/README.md

Command to log in for uploads, with options for password entry or email code retrieval.

```bash
node plethora.js login
```

--------------------------------

### External Dependencies Declaration

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/CLAUDE.md

Example of declaring external dependencies in `plethora.json`.

```json
dependencies: ['three@0.164.1']
```

--------------------------------

### Upload Workflow - ZIP package

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/BIT_BEST_PRACTICES.md

Command-line instructions for building and uploading a ZIP package containing a bit.

```bash
cd zip-build
Compress-Archive -Path main.js,plethora.json -DestinationPath ../my-bit.zip -Force
cd ..
plethora upload my-bit.zip --title "My Bit"
```

--------------------------------

### Permissions Declaration

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/CLAUDE.md

Example of declaring permissions required by a Plethora bit.

```javascript
permissions: ['backgroundMusic', 'audio', 'haptics', 'networkFetch']
```

--------------------------------

### Upload Workflow - Single JS file

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/BIT_BEST_PRACTICES.md

Command-line instructions for building and uploading a single JavaScript file.

```bash
npm install
npm run build
npm run check
plethora upload dist/bit.js --title "My Bit" --tags creative
```

--------------------------------

### Build and Check Commands

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/README.md

Commands to build the bit and check its validity against the Plethora contract.

```bash
npm run build
npm run check
```

--------------------------------

### Background Music Playback

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/CLAUDE.md

Example of how to play background music with fade-in, requiring the 'backgroundMusic' permission.

```javascript
let music;
ctx.listen(canvas, 'touchstart', () => {
  music ||= ctx.music.play({ preset: 'pulse', volume: 0.18, fadeInMs: 500 });
}, { once: true });
```

--------------------------------

### Build Commands for WebGPU Bits

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/BITS_CATALOGUE.md

Commands to bundle and upload WebGPU bits.

```bash
# WebGPU bits (need bundling)
node -e "require('esbuild').build({ entryPoints:['webgpu-bits/pylons.js'], bundle:true, format:'iife', outfile:'dist/pylons.js', target:['es2020'], minify:true, conditions:['import','module'] })"
plethora upload dist/pylons.js --title "pylons" --tags creative
```

--------------------------------

### qbert.js init() Function Data

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/graphify-out/graph.html

Data structure for the 'init()' function within the 'qbert.js' community, detailing its ID, label, color, size, font properties, title, community ID and name, source file, file type, and degree.

```json
{
  "id": "qbert\_init",
  "label": "init()",
  "color": {"bac
```

--------------------------------

### Surface Ownership - Avoid

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/CLAUDE.md

Examples of API usage to avoid when developing Plethora bits, related to DOM manipulation and global event listeners.

```javascript
document.createElement('canvas');
document.body.appendChild(node);
document.documentElement.appendChild(node);
requestAnimationFrame(loop);
window.addEventListener('resize', onResize);
document.addEventListener('touchstart', onTouch);

```

--------------------------------

### Plethora Bit Package Layout

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/CLAUDE.md

Standard directory structure for a Plethora bit package.

```text
my-bit/
  main.js
  plethora.json
```

--------------------------------

### Network Initialization and Options

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/graphify-out/graph.html

Initializes the network graph with specified options for stabilization, interaction, nodes, and edges. It also sets physics to be disabled after stabilization.

```javascript
const network = new Network(container, data, {
  physics: {
    stabilization: { iterations: 200, fit: true },
  },
  interaction: {
    hover: true,
    tooltipDelay: 100,
    hideEdgesOnDrag: true,
    navigationButtons: false,
    keyboard: false,
  },
  nodes: {
    shape: 'dot',
    borderWidth: 1.5
  },
  edges: {
    smooth: {
      type: 'continuous',
      roundness: 0.2
    },
    selectionWidth: 3
  }
});
network.once('stabilizationIterationsDone', () => {
  network.setOptions({ physics: { enabled: false } });
});
```

--------------------------------

### ZIP Package Check Command

Source: https://github.com/zenarenarin/plethora-bit-starter/blob/main/CLAUDE.md

Command to check a ZIP package directory for a Plethora bit.

```bash
node scripts/check-package.js ./zip-build
```
Tokens:
Raw