Skip to content

Commit

Permalink
Merge pull request #47 from ccrma/dev
Browse files Browse the repository at this point in the history
WebChucK v1.2.9
  • Loading branch information
terryzfeng authored Oct 24, 2024
2 parents 34ad2cc + 5237e23 commit 5e930cf
Show file tree
Hide file tree
Showing 57 changed files with 3,598 additions and 321 deletions.
41 changes: 33 additions & 8 deletions DEVELOPER_GUIDE.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,18 @@
# WebChucK Developer Guide

Getting started with WebChucK development! **NOTE**: All development is done on the `dev` branch. `main` is reserved for releases.
How to contribute to WebChucK development!

**NOTE**: All development is done on the `dev` branch. `main` is reserved for
release.

## Table of Contents
1. [Setup](#setup)
2. [Building](#building)
3. [Testing](#testing)
4. [Documentation](#documentation)
- [WebChucK Developer Guide](#webchuck-developer-guide)
- [Table of Contents](#table-of-contents)
- [Setup](#setup)
- [Building](#building)
- [Testing](#testing)
- [Documentation](#documentation)
- [Deploy and Release](#deploy-and-release)

## Setup

Expand All @@ -32,19 +38,23 @@ Build WebChucK by running:
npm run build
```

This will build WebChucK and place all necessary files in the `./dist` folder. Additionally, it will build `./src/wc-bundle` which is the bundled ESM module of WebChucK (essentially all of `./dist`) for local use.
This will build WebChucK and place all necessary files in the `./dist` folder.
Additionally, it will build `./src/wc-bundle` which is the bundled ESM module of
WebChucK (essentially all of `./dist`) for local use.

## Testing

After you've built WebChucK, serve this repository using your local server. Then open `./test/index.html` in your browser.
After you've built WebChucK, serve this repository using your local server. Then
open `./test/index.html` in your browser.

You can do this on your own or simply run

```
npm run test
```

Run the test bench in the browser, verifying tests pass and sound is made. To debug tests and print or write more tests, modify `./test/chuckTest.js`.
Run the test bench in the browser, verifying tests pass and sound is made. To
debug tests and print or write more tests, modify `./test/chuckTest.js`.

## Documentation

Expand All @@ -55,3 +65,18 @@ npm run doc
```

View the documentation at `./docs/index.html`

## Deploy and Release

To package and release a new version of WebChucK, make sure all changes are PR'ed onto the `main` branch. From main, build source and documentation, tag the release and publish the package to NPM using:

```
npm run build
npm run doc
npm version patch
npm publish
```

WebChucK is published here: [https://www.npmjs.com/package/webchuck](https://www.npmjs.com/package/webchuck)

Talk to **@gewang** to update the [WebChucK](https://chuck.stanford.edu/webchuck) site.
18 changes: 13 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ Try out WebChucK in action through [WebChucK IDE](https://chuck.stanford.edu/ide

### NPM

Install WebChucK via npm and use it with TypeScript:
Install WebChucK via [npm](https://www.npmjs.com/package/webchuck). WebChucK also
supports TypeScript:

```
npm install webchuck
Expand Down Expand Up @@ -51,17 +52,21 @@ if (theChuck.context.state === "suspended") {

### CDN

You can also embed WebChucK as a JS module into your `index.html`.
You can also embed WebChucK as a JavaScript module into your `index.html`.

```html
<html>
<head>
<script type="module" defer>
import { Chuck } from 'https://cdn.jsdelivr.net/npm/webchuck/+esm';
let theChuck; // global variable
document.getElementById('action').addEventListener('click', async () => {
// Initialize default ChucK object, if not already initialized
window.theChuck ??= await Chuck.init([]);
// Initialize default ChucK object
if (theChuck === undefined) {
theChuck = await Chuck.init([]);
}
// Run ChucK code
theChuck.runCode(`
SinOsc sin => dac;
Expand All @@ -77,7 +82,10 @@ You can also embed WebChucK as a JS module into your `index.html`.
</html>
```

You now have a WebChucK instance in the global variable `theChuck`. Read the [API reference](https://chuck.stanford.edu/webchuck/docs) to see how to communicate between JS and ChucK e.g. removing shreds, syncing variables, monitoring the VM etc.
`theChuck` contains the ChucK Virtual Machine for running code, removing shreds,
syncing global variables, and more! Read the
[documentation](https://chuck.stanford.edu/webchuck/docs/classes/Chuck.html)
for the full API reference.

## Documentation

Expand Down
57 changes: 57 additions & 0 deletions dist/Accel.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
import Chuck from "./Chuck";
/**
* Introducing Accel (accelerometer, on mobile) support for WebChucK. Accel wraps
* JavaScript DeviceMotionEvent listeners easing access to mobile device accelerometers
* in WebChucK code.
*
* To get started with Accel:
* @example
* ```ts
* import { Chuck, Accel } from "webchuck";
*
* const theChuck = await Chuck.init([]);
* const accel = await Accel.init(theChuck); // Initialize Accel
* ```
*/
export default class Accel {
private theChuck;
private _accelActive;
private boundHandleMotion;
/** @internal */
constructor(theChuck: Chuck);
/**
* Initialize Accel functionality in your WebChucK instance.
* This adds a `Accel` and `AccelMsg` class to the ChucK Virtual Machine (VM).
* Accelerometer event (DeviceMotionEvent) listeners are added if `enableAccel` is true (default).
* @example
* ```ts
* theChuck = await Chuck.init([]);
* accel = await Accel.init(theChuck); // Initialize Accel
*/
static init(theChuck: Chuck, enableAccel?: boolean): Promise<Accel>;
/**
* @internal
* Check if accel is active
*/
accelActive(): Promise<void>;
/**
* Enable Javascript event (DeviceMotionEvent) listeners for Accel
* @example
* ```ts
* // If accel is not yet enabled
* accel.enableAccel();
* ```
*/
enableAccel(): void;
/**
* Disable Javascript event (DeviceMotionEvent) listeners for Accel
* @example
* ```ts
* // If accel is enabled
* accel.disableAccel();
* ```
*/
disableAccel(): void;
/** @internal */
private handleMotion;
}
105 changes: 105 additions & 0 deletions dist/Accel.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
import { Accel_ck, AccelMsg_ck } from "./accelCk";
/**
* Introducing Accel (accelerometer, on mobile) support for WebChucK. Accel wraps
* JavaScript DeviceMotionEvent listeners easing access to mobile device accelerometers
* in WebChucK code.
*
* To get started with Accel:
* @example
* ```ts
* import { Chuck, Accel } from "webchuck";
*
* const theChuck = await Chuck.init([]);
* const accel = await Accel.init(theChuck); // Initialize Accel
* ```
*/
export default class Accel {
/** @internal */
constructor(theChuck) {
this._accelActive = false;
// Initialize members
this.theChuck = theChuck;
this.boundHandleMotion = this.handleMotion.bind(this);
}
/**
* Initialize Accel functionality in your WebChucK instance.
* This adds a `Accel` and `AccelMsg` class to the ChucK Virtual Machine (VM).
* Accelerometer event (DeviceMotionEvent) listeners are added if `enableAccel` is true (default).
* @example
* ```ts
* theChuck = await Chuck.init([]);
* accel = await Accel.init(theChuck); // Initialize Accel
*/
static async init(theChuck, enableAccel = true) {
const accel = new Accel(theChuck);
// Add Accel and AccelMsg classes to ChucK VM
await accel.theChuck.runCode(AccelMsg_ck);
await accel.theChuck.runCode(Accel_ck);
// Enable mouse and keyboard
/*
if (enableAccel) {
// If iOS, request permission
if (typeof (DeviceOrientationEvent as any).requestPermission === 'function') {
const permission = await (DeviceOrientationEvent as any).requestPermission();
if (permission === 'granted') {
accel.enableAccel();
} else {
console.log("Accelscope permission denied.");
}
} else {
// just try to enable
accel.enableAccel();
}
}
*/
accel.enableAccel();
return accel;
}
/**
* @internal
* Check if accel is active
*/
async accelActive() {
const x = await this.theChuck.getInt("_accelActive");
this._accelActive = x == 1;
}
/**
* Enable Javascript event (DeviceMotionEvent) listeners for Accel
* @example
* ```ts
* // If accel is not yet enabled
* accel.enableAccel();
* ```
*/
enableAccel() {
// consider using "deviceorientationabsolute"
// https://developer.mozilla.org/en-US/docs/Web/API/Window/deviceorientationabsolute_event
window.addEventListener("devicemotion", this.boundHandleMotion);
}
/**
* Disable Javascript event (DeviceMotionEvent) listeners for Accel
* @example
* ```ts
* // If accel is enabled
* accel.disableAccel();
* ```
*/
disableAccel() {
window.removeEventListener("devicemotion", this.boundHandleMotion);
}
//-----------------------------------------
// JAVASCRIPT HID EVENT HANDLERS
//-----------------------------------------
/** @internal */
handleMotion(event) {
this.accelActive();
if (this._accelActive) {
if (event.acceleration != null) {
this.theChuck.setFloat("_accelX", event.acceleration.x ? event.acceleration.x : 0.0);
this.theChuck.setFloat("_accelY", event.acceleration.y ? event.acceleration.y : 0.0);
this.theChuck.setFloat("_accelZ", event.acceleration.z ? event.acceleration.z : 0.0);
this.theChuck.broadcastEvent("_accelReading");
}
}
}
}
Loading

0 comments on commit 5e930cf

Please sign in to comment.