@turbowarp/types 0.0.4 → 0.0.6

package/README.md

@@ -2,9 +2,7 @@
 
 Scratch doesn't provide type definitions for their libraries, so we wrote our own.
 
-This project is still at an early stage.
-
-Despite being in the TurboWarp organization, this project is currently focused only on the vanilla (LLK) Scratch runtime and editor. Additional types for TurboWarp may be added later.
+This repository only contains types for the vanilla (LLK) Scratch runtime and editor. For the additional types in the TurboWarp runtimes, see [@turbowarp/types-tw](https://github.com/TurboWarp/types-tw).
 
 |Module|Status|
 |:-:|:-:|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turbowarp/types",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Type definitions for the Scratch VM and editor",
   "keywords": [
     "scratch"

package/tests/test-jszip.ts

@@ -0,0 +1,16 @@
+declare const stream: JSZip.StreamHelper<'uint8array'>;
+
+stream.on('data', data => {
+    data as Uint8Array
+});
+stream.on('data', (data, metadata) => {
+    metadata.percent as number
+});
+
+stream.pause();
+stream.resume();
+
+// @ts-expect-error
+stream.on('whatever', () => {
+
+});

package/tests/{scratch-audio.ts → test-scratch-audio.ts}

@@ -15,3 +15,11 @@ audioEngine.decodeSoundPlayer({
     });
     return player.finished();
   });
+
+declare const pitchEffect: AudioEngine.PitchEffect;
+pitchEffect.ratio as number
+pitchEffect.updatePlayers([]);
+
+declare const soundPlayer: AudioEngine.SoundPlayer;
+
+new audioEngine.effects[0](audioEngine, soundPlayer, pitchEffect);

package/tests/test-scratch-vm-extension.js

@@ -0,0 +1,105 @@
+(function(Scratch) {
+  'use strict';
+
+  class Fetch {
+    /** @returns {Scratch.Info} */
+    getInfo () {
+      return {
+        id: 'fetch',
+        name: 'Fetch',
+        blocks: [
+          {
+            opcode: 'get',
+            blockType: Scratch.BlockType.REPORTER,
+            text: 'GET [URL]',
+            arguments: {
+              URL: {
+                type: Scratch.ArgumentType.STRING,
+                defaultValue: 'https://extensions.turbowarp.org/hello.txt'
+              }
+            }
+          },
+          {
+            opcode: 'test',
+            text: 'test [STRING] [IMAGE] [BOOLEAN] [NUMBER] [MATRIX] [NOTE] [ANGLE] [COLOR]',
+            blockType: Scratch.BlockType.COMMAND,
+            hideFromPalette: false,
+            isTerminal: true,
+            arguments: {
+              STRING: {
+                type: Scratch.ArgumentType.STRING,
+                defaultValue: 'test',
+                menu: 'test1'
+              },
+              IMAGE: {
+                type: Scratch.ArgumentType.IMAGE,
+                dataURI: 'https://extensions.turbowarp.org/dango.png'
+              },
+              BOOLEAN: {
+                type: Scratch.ArgumentType.BOOLEAN
+              },
+              NUMBER: {
+                type: Scratch.ArgumentType.NUMBER,
+                defaultValue: 5,
+              },
+              MATRIX: {
+                type: Scratch.ArgumentType.MATRIX,
+                defaultValue: '0101001010000001000101110'
+              },
+              NOTE: {
+                type: Scratch.ArgumentType.NOTE,
+                defaultValue: '30'
+              },
+              ANGLE: {
+                type: Scratch.ArgumentType.ANGLE,
+                defaultValue: 30
+              },
+              COLOR: {
+                type: Scratch.ArgumentType.COLOR,
+                defaultValue: '#123456'
+              }
+            }
+          },
+          {
+            opcode: 'button',
+            blockType: Scratch.BlockType.BUTTON,
+            func: 'MAKE_A_VARIABLE',
+            text: 'button text'
+          }
+        ],
+        menus: {
+          test1: ['1', '2', '3'],
+          test2: {
+            acceptReporters: false,
+            items: [
+              { text: 'text', value: 'value' },
+              'another value'
+            ]
+          }
+        }
+      };
+    }
+
+    /**
+     * @param {{URL: string;}} args
+     */
+    get (args) {
+      return fetch(args.URL)
+        .then(r => r.text())
+        .catch(() => '');
+    }
+
+    /**
+     * @param {unknown} args
+     */
+    test (args) {
+      console.log(args);
+    }
+  }
+
+  if (Scratch.extensions.unsandboxed) {
+    // ...
+  }
+
+  Scratch.extensions.register(new Fetch());
+})(Scratch);

package/tests/{vm.ts → test-scratch-vm.ts}

@@ -53,3 +53,15 @@ if (target) {
 const audioEngine = new AudioEngine();
 vm.attachAudioEngine(audioEngine);
 audioEngine.audioContext.suspend();
+
+vm.setTurboMode(true);
+vm.runtime.turboMode as boolean
+vm.setCompatibilityMode(true);
+vm.runtime.compatibilityMode as boolean
+
+const costume = vm.runtime.getTargetForStage()?.getCostumes()?.[0];
+costume?.skinId as number;
+
+declare const util: VM.BlockUtility;
+util.startHats('hats', {BROADCAST_OPTION: 'test'}) as VM.Thread[];
+util.ioQuery('mouse', 'getIsDown', []);

package/tests/test-scratchx-extension.js

@@ -0,0 +1,29 @@
+(function () {
+  const ext = {};
+
+  ext._getStatus = () => ({
+    status: 2,
+    msg: 'Ready'
+  });
+
+  ext.testReporter = () => Math.random();
+
+  /**
+   * @param {number} delay
+   * @param {function} callback
+   */
+  ext.testReporterWait = (delay, callback) => {
+    setTimeout(() => {
+      callback(Math.random())
+    }, delay * 1000);
+  };
+
+  var descriptor = {
+    blocks: [
+      ['r', 'test reporter', 'testReporter'],
+      ['R', 'test reporter 2 %n', 'testReporterWait', '1'],
+    ],
+  };
+  
+  ScratchExtensions.register('ScratchX Test', descriptor, ext);
+}());

package/types/jszip.d.ts

@@ -3,6 +3,30 @@
 
 declare namespace JSZip {
   // TODO
+
+  interface OutputTypes {
+    base64: string;
+    binarystring: string;
+    array: number[];
+    uint8array: Uint8Array;
+    arraybuffer: ArrayBuffer;
+    blob: Blob;
+    nodebuffer: Uint8Array; // actually a Node.js Buffer
+  }
+
+  interface ProgressMetadata {
+    percent: number;
+    currentFile: string;
+  }
+
+  interface StreamHelper<T extends keyof OutputTypes> {
+    resume(): void;
+    pause(): void;
+    on(event: 'data', callback: (data: OutputTypes[T], metadata: ProgressMetadata) => void): void;
+    on(event: 'end', callback: () => void): void;
+    on(event: 'error', callback: (error: Error) => void): void;
+    accumulate(updateCallback?: (metadata: ProgressMetadata) => void): Promise<OutputTypes[T]>;
+  }
 }
 
 declare class JSZip {

package/types/scratch-audio.d.ts

@@ -19,10 +19,10 @@ declare namespace AudioEngine {
     getLoudness(): number;
   }
 
-  interface Effect {
+  interface AbstractEffect {
     audioEngine: AudioEngine;
     audioPlayer: SoundPlayer;
-    lastEffect: Effect;
+    lastEffect: AbstractEffect;
     value: number;
     initialized: boolean;
     initialize(): void;
@@ -41,11 +41,36 @@ declare namespace AudioEngine {
     dispose(): void;
   }
 
+  interface PitchEffect extends AbstractEffect {
+    get name(): 'pitch';
+    ratio: number;
+    getRatio(val: number): number;
+    updatePlayer(soundPlayer: SoundPlayer): void;
+    updatePlayers(soundPlayers: Record<string, SoundPlayer> | SoundPlayer[]): void;
+  }
+
+  interface PanEffect extends AbstractEffect {
+    get name(): 'pan';
+    leftGain: GainNode;
+    rightGain: GainNode;
+    channelMerger: ChannelMergerNode;
+  }
+
+  interface VolumeEffect extends AbstractEffect {
+    get name(): 'volume';
+  }
+
+  type Effect = PitchEffect | PanEffect | VolumeEffect;
+
+  interface EffectConstructor {
+    new(audioEngine: AudioEngine, soundPlayer: SoundPlayer, lastEffect: Effect | null): Effect;
+  }
+
   interface EffectChain {
     audioEngine: AudioEngine;
     inputNode: GainNode;
     getInputNode(): GainNode;
-    effects: Effect[];
+    effects: EffectConstructor[];
     _effects: Effect[];
     firstEffect: Effect;
     lastEffect: Effect;
@@ -86,14 +111,32 @@ declare namespace AudioEngine {
     stopImmediately(): void;
     finished(): Promise<void>;
     setPlaybackRate(playbackRate: number): void;
+    take(): SoundPlayer;
   }
 
   interface SoundBank {
     audioEngine: AudioEngine;
+
+    /**
+     * Maps sound ID to its sound player.
+     */
     soundPlayers: Record<string, SoundPlayer>;
-    playerTargets: Record<string, Target>;
-    soundEffects: Record<string, EffectChain>;
+
+    /**
+     * Maps sound IDs to the target they were most recently been started by.
+     */
+    playerTargets: Map<string, Target>;
+
+    /**
+     * Maps sound IDs to their effect chain.
+     */
+    soundEffects: Map<string, EffectChain>;
+
+    /**
+     * Original effect chain cloned for each sound.
+     */
     effectChainPrime: EffectChain;
+
     addSoundPlayer(soundPlayer: SoundPlayer): void;
     getSoundPlayer(soundId: string): SoundPlayer | undefined;
     getSoundEffects(soundId: string): EffectChain;
@@ -128,7 +171,8 @@ declare class AudioEngine {
    */
   getLoudness(): number;
 
-  effects: AudioEngine.Effect[];
+  effects: AudioEngine.EffectConstructor[];
+
   get EFFECT_NAMES(): Record<string, string>;
   get DECAY_DURATION(): number;
   get DECAY_WAIT(): number;

package/types/scratch-vm-extension.d.ts

@@ -0,0 +1,251 @@
+declare namespace Scratch {
+  // Note that the 'B' in the BOOLEAN enums are capitalized in Scratch. It is not a typo in this file.
+
+  namespace ArgumentType {
+    const ANGLE: 'angle';
+    const BOOLEAN: 'Boolean';
+    const COLOR: 'color';
+    const IMAGE: 'image';
+    const MATRIX: 'matrix';
+    const NOTE: 'note';
+    const NUMBER: 'number';
+    const STRING: 'string';
+  }
+
+  namespace BlockType {
+    const BOOLEAN: 'Boolean';
+    /** @deprecated very incomplete and not useful yet */
+    const BUTTON: 'button';
+    const COMMAND: 'command';
+    /** @deprecated does not work in compiler */
+    const CONDITIONAL: 'conditional';
+    /** @deprecated use HAT instead */
+    const EVENT: 'event';
+    const HAT: 'hat';
+    /** @deprecated does not work in compiler */
+    const LOOP: 'loop';
+    const REPORTER: 'reporter';
+  }
+
+  namespace TargetType {
+    const SPRITE: 'sprite';
+    const STAGE: 'stage';
+  }
+
+  interface AngleArgument {
+    type: 'angle';
+    /**
+     * Defaults to 0.
+     */
+    defaultValue?: string | number;
+  }
+  interface BooleanArgument {
+    type: 'Boolean';
+  }
+  interface ColorArgument {
+    type: 'color';
+    /**
+     * Should be a hex color code. No alpha channel supported. Defaults to random color.
+     */
+    defaultValue?: string | number;
+  }
+  interface NumberArgument {
+    type: 'number';
+    /**
+     * Defaults to 0.
+     */
+    defaultValue?: string | number;
+    menu?: string;
+  }
+  interface StringArgument {
+    type: 'string';
+    /**
+     * Defaults to empty string.
+     */
+    defaultValue?: string | number;
+    menu?: string;
+  }
+  interface MatrixArgument {
+    type: 'matrix';
+    /**
+     * Should be a 25 character long string of 1s and 0s.
+     * Numbers are technically accepted, but be aware that due to floating point precision, some detail may be lost.
+     * Technically optional, but behaves strangely with no default value.
+     */
+    defaultValue?: string | number;
+  }
+  interface NoteArgument {
+    type: 'note';
+    /**
+     * Defaults to 0 ("C (0)")
+     */
+    defaultValue?: string | number;
+  }
+  interface ImageArgument {
+    type: 'image';
+    dataURI: string;
+    /**
+     * Defaults to false.
+     */
+    flipRTL?: boolean;
+  }
+  type Argument = (
+    AngleArgument |
+    BooleanArgument |
+    ColorArgument |
+    NumberArgument |
+    StringArgument |
+    MatrixArgument |
+    NoteArgument |
+    ImageArgument
+  );
+
+  interface AbstractBlock {
+    opcode: string;
+    func?: string;
+    text: string | string[];
+    arguments?: Record<string, Argument>;
+    hideFromPalette?: boolean;
+    filter?: Array<'target' | 'sprite'>;
+    blockIconURI?: string;
+  }
+  interface BooleanBlock extends AbstractBlock {
+    blockType: 'Boolean';
+  }
+  interface ButtonBlock extends AbstractBlock {
+    blockType: 'button';
+    func: 'MAKE_A_LIST' | 'MAKE_A_PROCEDURE' | 'MAKE_A_VARIABLE';
+  }
+  interface CommandBlock extends AbstractBlock {
+    blockType: 'command';
+    /**
+     * Defaults to false.
+     */
+    isTerminal?: boolean;
+  }
+  interface ConditionalBlock extends AbstractBlock {
+    blockType: 'conditional';
+    /**
+     * Defaults to false.
+     */
+    isTerminal?: boolean;
+    /**
+     * Defaults to 1.
+     */
+    branchCount?: number;
+  }
+  interface EventBlock extends AbstractBlock {
+    blockType: 'event';
+    /**
+     * This must be explicitly set to false, otherwise the block will not work.
+     * Event blocks cannot be edge activated. Use hat instead.
+     */
+    isEdgeActivated: false;
+    /**
+     * Defaults to false.
+     */
+    shouldRestartExistingThreads?: boolean;
+  }
+  interface HatBlock extends AbstractBlock {
+    blockType: 'hat';
+    /**
+     * Defaults to true.
+     */
+    isEdgeActivated?: boolean;
+    /**
+     * Defaults to false.
+     */
+    shouldRestartExistingThreads?: boolean;
+  }
+  interface ReporterBlock extends AbstractBlock {
+    blockType: 'reporter';
+    /**
+     * Defaults to false.
+     */
+    disableMonitor?: boolean;
+  }
+  interface LoopBlock extends AbstractBlock {
+    blockType: 'loop';
+    /**
+     * Defaults to false.
+     */
+    isTerminal?: boolean;
+    /**
+     * Defaults to 1.
+     */
+    branchCount?: number;
+  }
+  type Block = (
+    BooleanBlock |
+    ButtonBlock |
+    CommandBlock |
+    ConditionalBlock |
+    EventBlock |
+    HatBlock |
+    ReporterBlock |
+    LoopBlock
+  );
+
+  interface Menu {
+    acceptReporters?: boolean;
+    /**
+     * A list of static items in the menu, or the name of the dynamic menu function.
+     */
+    items: Array<string | {
+      text: string;
+      value: string;
+    }> | string;
+  }
+
+  interface Info {
+    id: string;
+
+    /**
+     * Defaults to extension ID if not specified.
+     */
+    name?: string;
+
+    /**
+     * Should be a hex color code.
+     */
+    color1?: string;
+
+    /**
+     * Should be a hex color code.
+     */
+    color2?: string;
+
+    /**
+     * Should be a hex color code.
+     */
+    color3?: string;
+
+    /**
+     * Should be a data: URI
+     */
+    menuIconURI?: string;
+
+    /**
+     * Should be a data: URI
+     */
+    blockIconURI?: string;
+
+    docsURI?: string;
+
+    blocks: (Block | string)[];
+    menus?: Record<string, Menu | string[]>;
+  }
+
+  interface Extension {
+    getInfo(): Info;
+  }
+
+  namespace extensions {
+    function register(extensionObject: Extension): void;
+  
+    /**
+     * True if the extension is running unsandboxed, otherwise undefined.
+     */
+    const unsandboxed: undefined | boolean;
+  }
+}

package/types/scratch-vm.d.ts

@@ -60,6 +60,7 @@ declare namespace VM {
     rotationCenterX: number;
     rotationCenterY: number;
     size: [number, number];
+    skinId: number;
   }
 
   interface Sound extends BaseAsset {
@@ -613,7 +614,72 @@ declare namespace VM {
   }
 
   interface StackFrame {
-    // TODO
+    isLoop: boolean;
+    warpMode: boolean;
+    justReported: unknown;
+    reporting: string;
+    reported: unknown;
+    /** @deprecated unused */
+    waitingReporter: unknown;
+    params: unknown;
+    executionContext: unknown;
+    reset(): void;
+  }
+
+  interface BlockUtility {
+    sequencer: Sequencer;
+    thread: Thread;
+    _nowObj: {
+      now(): number;
+    };
+    nowObj: BlockUtility['_nowObj'],
+    target: Target;
+    runtime: Runtime;
+    stackFrame: StackFrame;
+    stackTimerFinished(): boolean;
+    stackTimerNeedsInit(): boolean;
+    startStackTimer(milliseconds: number): void;
+    yield(): void;
+    yieldTick(): void;
+    startBranch(branchNumber: number, isLoop: boolean): void;
+    /**
+     * @see {Runtime.stopAll}
+     */
+    stopAll(): void;
+    /**
+     * @see {Runtime.stopForTarget}
+     */
+    stopOtherTargetThreads(): void;
+    /**
+     * @see {Thread.stopThisScript}
+     */
+    stopThisScript(): void;
+    /**
+     * @see {Blocks.getProcedureParamNamesAndIds}
+     */
+    getProcedureParamNamesAndIds(): [string[], string[]];
+    /**
+     * @see {Blocks.getProcedureParamNamesIdsAndDefaults}
+     */
+    getProcedureParamNamesIdsAndDefaults(): [string[], string[], string[]];
+    /**
+     * @see {Thread.initParams}
+     */
+    initParams(): void;
+    /**
+     * @see {Thread.pushParam}
+     */
+    pushParam(name: string, value: ScratchCompatibleValue): void;
+    /**
+     * @see {Thread.getParam}
+     */
+    getParam(name: string): ScratchCompatibleValue;
+    /**
+     * Use instead of runtime.startHats inside blocks.
+     * @see {Runtime.startHats}
+     */
+    startHats: Runtime['startHats'];
+    ioQuery<Device extends keyof IODevices>(device: Device, func: keyof IODevices[Device], args: unknown[]): unknown;
   }
 
   const enum ThreadStatus {
@@ -636,16 +702,19 @@ declare namespace VM {
     blockGlowInFrame: string | null;
     warpTimer: Timer | null;
     justReported: unknown;
+    reuseStackForNextBlock(blockId: string): void;
     pushStack(blockId: string): void;
     popStack(): string;
     peekStack(): string;
     peekStackFrame(): StackFrame | null;
     peekParentStackFrame(): StackFrame | null;
+    pushReportedValue(value: ScratchCompatibleValue): void;
     initParams(): void;
     pushParam(name: string, value: ScratchCompatibleValue): void;
     getParam(name: string): ScratchCompatibleValue | null;
     atStackTop(): boolean;
     goToNextBlock(): void;
+    stopThisScript(): void;
     isRecursiveCall(procedureCode: string): boolean;
     stackClick: boolean;
     updateMonitor: boolean;
@@ -817,6 +886,8 @@ declare namespace VM {
     _isDown: boolean;
     getIsDown(): boolean;
     postData(data: MouseData): void;
+    _activateClickHats(target: Target): void;
+    _pickTarget(x: number, y: number): Target;
   }
 
   interface MouseWheelData {
@@ -1014,6 +1085,13 @@ declare namespace VM {
      */
     _step(): void;
 
+    turboMode: boolean;
+
+    /**
+     * If true, the runtime is running at 60 FPS. If false, the runtime is running at 30 FPS.
+     */
+    compatibilityMode: boolean;
+
     renderer: IfRenderer<RenderWebGL, undefined>;
 
     attachRenderer(renderer: RenderWebGL): void;
@@ -1107,7 +1185,7 @@ declare namespace VM {
 
     _getMonitorThreadCount(threads: Thread[]): number;
 
-    startHats(opcode: string, matchFields?: Record<string, unknown>, target?: Target): void;
+    startHats(opcode: string, matchFields?: Record<string, unknown>, target?: Target): Thread[];
 
     toggleScript(topBlockId: string, options?: {
       target?: string;

package/types/scratchx-extension.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @deprecated ScratchX is deprecated. Do not use in new extensions.
+ */
+declare namespace ScratchExtensions {
+  /**
+   * @deprecated ScratchX is deprecated. Do not use in new extensions.
+   */
+  function register(name: string, descriptor: unknown, extension: unknown): void;
+}