@turbowarp/types 0.0.3 → 0.0.5

package/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Our goal is to document all the APIs exposed by Scratch. We accept any contributions that work towards that goal.
+
+Even if you aren't able to write types, please open issues to report missing or incorrect types.
+
+In terms of code style, we aren't super picky. Just keep it consistent with whatever is already there.
+
+For very complex types, please add a small test case in the `tests` directory. Presumably you already wrote some test code while writing the types, so just don't delete that once you're done.

package/package.json

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

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,36 @@
+(function(Scratch) {
+  'use strict';
+
+  class Fetch {
+    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'
+              }
+            }
+          }
+        ]
+      };
+    }
+
+    /**
+     * @param {{URL: string;}} args
+     */
+    get (args) {
+      return fetch(args.URL)
+        .then(r => r.text())
+        .catch(() => '');
+    }
+  }
+
+  Scratch.extensions.register(new Fetch());
+})(Scratch);

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

@@ -53,3 +53,11 @@ 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;

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/paper.d.ts

@@ -9,4 +9,9 @@ declare namespace Paper {
   interface Matrix {
     // TODO
   }
+
+  interface Tool {
+    // TODO
+    activate(): void;
+  }
 }

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-gui.d.ts

@@ -452,73 +452,73 @@ declare namespace ScratchGUI {
     {
       type: 'scratch-gui/project-state/DONE_CREATING_COPY';
       projectId: string;
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/DONE_CREATING_NEW';
       projectId: string;
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/DONE_FETCHING_DEFAULT';
       projectData: ProjectData;
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/DONE_FETCHING_WITH_ID';
       projectData: ProjectData;
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/DONE_LOADING_VM_TO_SAVE';
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/DONE_LOADING_VM_WITH_ID';
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/DONE_LOADING_VM_WITHOUT_ID';
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/DONE_REMIXING';
       projectId: string;
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/DONE_UPDATING';
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/DONE_UPDATING_BEFORE_COPY';
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/DONE_UPDATING_BEFORE_NEW';
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/RETURN_TO_SHOWING';
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/SET_PROJECT_ID';
       projectId: string;
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/START_AUTO_UPDATING';
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/START_CREATING_NEW';
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/START_ERROR';
       error: unknown;
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/START_FETCHING_NEW';
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/START_LOADING_VM_FILE_UPLOAD';
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/START_MANUAL_UPDATING';
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/START_REMIXING';
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/START_UPDATING_BEFORE_CREATING_COPY';
-    } | 
+    } |
     {
       type: 'scratch-gui/project-state/START_UPDATING_BEFORE_CREATING_NEW';
     } |

package/types/scratch-paint.ts

@@ -171,7 +171,7 @@ declare namespace ScratchPaint {
     {
       type: 'scratch-paint/eye-dropper/ACTIVATE_COLOR_PICKER';
       callback: ScratchPaintState['color']['eyeDropper']['callback'];
-      previousMode: Mode;
+      previousMode: Paper.Tool;
     } |
     {
       type: 'scratch-paint/eye-dropper/DEACTIVATE_COLOR_PICKER';

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

@@ -0,0 +1,133 @@
+/// <reference path="./scratch-vm.d.ts" />
+/// <reference path="./scratch-render.d.ts" />
+
+declare namespace Scratch {
+  namespace ArgumentType {
+    /** @deprecated not tested -- do not rely on yet */
+    const ANGLE: 'angle';
+    const BOOLEAN: 'Boolean';
+    /** @deprecated not tested -- do not rely on yet */
+    const COLOR: 'color';
+    const NUMBER: 'number';
+    const STRING: 'string';
+    /** @deprecated not tested -- do not rely on yet */
+    const MATRIX: 'matrix';
+    /** @deprecated not tested -- do not rely on yet */
+    const NOTE: 'note';
+    /** @deprecated not tested -- do not rely on yet */
+    const IMAGE: 'image';
+  }
+  type ArgumentType = (typeof ArgumentType)[keyof typeof ArgumentType];
+  
+  namespace BlockType {
+    // The B in Boolean is supposed to be capitalized
+    const BOOLEAN: 'Boolean';
+    /** @deprecated not tested -- do not rely on yet */
+    const BUTTON: 'button';
+    const COMMAND: 'command';
+    /** @deprecated not tested -- do not rely on yet */
+    const CONDITIONAL: 'conditional';
+    const EVENT: 'event';
+    const HAT: 'hat';
+    /** @deprecated not tested -- do not rely on yet */
+    const LOOP: 'loop';
+    const REPORTER: 'reporter';
+  }
+  type BlockType = (typeof BlockType)[keyof typeof BlockType];
+  
+  namespace TargetType {
+    const SPRITE: 'sprite';
+    const STAGE: 'stage';
+  }
+  type TargetType = (typeof TargetType)[keyof typeof TargetType];
+  
+  /**
+   * scratch-vm instance. Only for unsandboxed extensions.
+   */
+  const vm: VM;
+  
+  /**
+   * scratch-render instance. Only for unsandboxed extensions.
+   */
+  const renderer: RenderWebGL;
+  
+  /**
+   * Technically this can be a translatable object, but in reality it will probably just be
+   * a string here.
+   */
+  type FormattableString = string;
+  
+  interface ExtensionArgumentInfo {
+    type: ArgumentType;
+    defaultValue?: string | number;
+    menu?: string;
+  }
+  
+  interface ExtensionBlock {
+    opcode: string;
+    blockType: BlockType;
+    text: FormattableString;
+    arguments?: Record<string, ExtensionArgumentInfo>;
+    // TODO: documentation mentions func, filter, branchCount, terminal, blockAllThreads
+  }
+  
+  interface ExtensionMenu {
+    acceptReporters?: boolean;
+    items: Array<string | {
+      text: string;
+      value: string;
+    }>;
+  }
+  
+  interface ExtensionInfo {
+    id: string;
+  
+    /**
+     * Defaults to ID if not specified.
+     */
+    name?: FormattableString;
+  
+    /**
+     * 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: (ExtensionBlock | string)[];
+    menus?: Record<string, ExtensionMenu>;
+  }
+  
+  interface Extension {
+    getInfo(): ExtensionInfo;
+  }
+  
+  namespace extensions {
+    function register(extensionObject: Extension): void;
+  
+    /**
+     * True if the extension is running unsandboxed.
+     */
+    const unsandboxed: 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 {
@@ -76,6 +77,8 @@ declare namespace VM {
     name: string;
     costumes: Costume[];
     sounds: Sound[];
+    clones: RenderedTarget[];
+    soundBank: AudioEngine.SoundBank | null;
   }
 
   interface Field {
@@ -297,6 +300,8 @@ declare namespace VM {
 
     comments: Record<string, Comment>;
 
+    createComment(id: string, blockId: string, text: string, x: number, y: number, width: number, height: number, minimized?: boolean): void;
+
     /**
      * Called by runtime when the green flag is pressed.
      */
@@ -813,6 +818,8 @@ declare namespace VM {
     _isDown: boolean;
     getIsDown(): boolean;
     postData(data: MouseData): void;
+    _activateClickHats(target: Target): void;
+    _pickTarget(x: number, y: number): Target;
   }
 
   interface MouseWheelData {
@@ -990,6 +997,11 @@ declare namespace VM {
      */
     start(): void;
 
+    /**
+     * Stop all timers.
+     */
+    quit(): void;
+
     /**
      * Start "when green flag pressed" scripts.
      */
@@ -1005,6 +1017,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;
@@ -1297,6 +1316,11 @@ declare class VM extends EventEmitter<VM.VirtualMachineEventMap> {
    */
   start(): void;
 
+  /**
+   * @see {VM.Runtime.quit}
+   */
+  quit(): void;
+
   /**
    * @see {VM.Runtime.greenFlag}
    */

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;
+}