@dnd-ed/jsshenanigans 0.0.0-stage → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,28 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 itzdanti and JSShenanigans contributors
4
+ (jsshenanigans, https://github.com/dnd-ed/jsshenanigans)
5
+
6
+ Copyright (c) 2026 itzdanti and PythonShenanigans contributors
7
+ (pythonshenanigans, https://github.com/dnd-ed/pythonshenanigans)
8
+
9
+ Copyright (c) 2026 Formuna
10
+ (libjjs, https://github.com/FormunaGit/libjjs)
11
+
12
+ Permission is hereby granted, free of charge, to any person obtaining a copy
13
+ of this software and associated documentation files (the "Software"), to deal
14
+ in the Software without restriction, including without limitation the rights
15
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
16
+ copies of the Software, and to permit persons to whom the Software is
17
+ furnished to do so, subject to the following conditions:
18
+
19
+ The above copyright notice and this permission notice shall be included in all
20
+ copies or substantial portions of the Software.
21
+
22
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
25
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
27
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
28
+ SOFTWARE.
package/NOTICE.md ADDED
@@ -0,0 +1,89 @@
1
+ # NOTICE AND ATTRIBUTION
2
+
3
+ **JSShenanigans** --- a JavaScript library for creating, loading and modifying
4
+ Jujutsu Shenanigans movesets.
5
+
6
+ ## 1. Definitions
7
+
8
+ For the purposes of this Notice:
9
+
10
+ - **"the Work"** means the software known as JSShenanigans, including its
11
+ source code, documentation, and any accompanying materials, made available at
12
+ <https://github.com/dnd-ed/jsshenanigans>;
13
+ - **"the Reference Work"** means the software known as PythonShenanigans, made
14
+ available at <https://github.com/dnd-ed/pythonshenanigans>;
15
+ - **"the Upstream Work"** means the software known as libjjs, made available at
16
+ <https://github.com/FormunaGit/libjjs>; and
17
+ - **"You"** means any natural person or legal entity exercising rights under the
18
+ MIT License in respect of the Work.
19
+
20
+ ## 2. Statement of Derivation
21
+
22
+ The Work is a JavaScript port of the Reference Work, which is in turn inspired
23
+ by and partly derived from the Upstream Work. Substantial portions of the logic
24
+ of the Work are copied from, adapted from, or otherwise based upon the source
25
+ code of the Reference Work and the Upstream Work.
26
+
27
+ ## 3. Preservation and Reproduction of Copyright Notices
28
+
29
+ The Upstream Work is distributed under the MIT License, which provides that the
30
+ copyright notice and permission notice set out therein shall be included in all
31
+ copies or substantial portions of the Software.
32
+
33
+ Accordingly:
34
+
35
+ 1. the copyright notices of the Reference Work and the Upstream Work are
36
+ reproduced in the `LICENSE` file distributed with the Work, and shall not be
37
+ removed, altered, or obscured; and
38
+ 2. any person who copies, modifies, publishes, distributes, sublicenses, or
39
+ otherwise makes the Work, or any derivative work thereof, available to any
40
+ third party shall reproduce, in the documentation and/or other materials
41
+ provided with such distribution, **all** of the following notices:
42
+
43
+ > Copyright (c) 2026 itzdanti and JSShenanigans contributors
44
+ > (jsshenanigans, https://github.com/dnd-ed/jsshenanigans)
45
+ >
46
+ > Copyright (c) 2026 itzdanti and PythonShenanigans contributors
47
+ > (pythonshenanigans, https://github.com/dnd-ed/pythonshenanigans)
48
+ >
49
+ > Copyright (c) 2026 Formuna
50
+ > (libjjs, https://github.com/FormunaGit/libjjs)
51
+
52
+ The omission of any notice shall constitute a failure to satisfy the conditions
53
+ of the MIT License under which the Upstream Work is made available.
54
+
55
+ ## 4. Source Files Ported from the Reference Work
56
+
57
+ The following source files are ports of, and remain subject to the license of,
58
+ the Reference Work:
59
+
60
+ - `src/types.js`
61
+ - `src/nodes.js`
62
+ - `src/conditions.js`
63
+ - `src/defaults.js`
64
+ - `src/utils.js`
65
+ - `src/character.js`
66
+
67
+ ## 5. Source Files Original to the Work
68
+
69
+ The following source files were authored for the Work and are not direct ports:
70
+
71
+ - `src/codec.js`
72
+ - `src/errors.js`
73
+ - `src/tools.js`
74
+
75
+ ## 6. Disclaimer of Warranty
76
+
77
+ THE WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
78
+ INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
79
+ PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
80
+ COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
81
+ AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
82
+ WITH THE WORK OR THE USE OR OTHER DEALINGS IN THE WORK.
83
+
84
+ ## 7. No Affiliation; Trademarks
85
+
86
+ The Work is not affiliated with, endorsed by, or sponsored by the developers of
87
+ Jujutsu Shenanigans, Roblox Corporation, or the authors of the Reference Work or
88
+ the Upstream Work. "Jujutsu Shenanigans" and "Roblox" are the trademarks of
89
+ their respective owners and are used herein for identification purposes only.
package/README.md CHANGED
@@ -1,3 +1,98 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
+ <img src="https://raw.githubusercontent.com/dnd-ed/jsshenanigans/refs/heads/main/assets/jss_logo.png" alt="jsslogo" width="700" />
3
+ <br />
4
+ <em>the ssssnakiest way to build jjs movesets</em>
5
+ </div>
2
6
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
7
+ ![jsshenanigans on npm](https://img.shields.io/npm/v/@dnd-ed/jsshenanigans)
8
+
9
+ > [!IMPORTANT]
10
+ > This library is a JavaScript port of [PythonShenanigans](https://github.com/dnd-ed/pythonshenanigans),
11
+ > which is itself inspired by [FormunaGit/libjjs](https://github.com/FormunaGit/libjjs).
12
+ > When publishing code that uses this library, please credit
13
+ > *"itzdanti and JSShenanigans contributors (jsshenanigans, https://github.com/dnd-ed/jsshenanigans)"*,
14
+ > *"itzdanti and PythonShenanigans contributors (pythonshenanigans, https://github.com/dnd-ed/pythonshenanigans)"*,
15
+ > and *"Formuna (libjjs, https://github.com/FormunaGit/libjjs)"*.
16
+
17
+ ## How?
18
+
19
+ <details>
20
+ <summary>TL;DR, character codes are generated by compressing JSON through zstd and base64-encoding it.</summary>
21
+
22
+ The way character codes are generated is by taking the original JSON and
23
+ compressing it through [zstd](https://github.com/facebook/zstd) and then
24
+ base64-encoding it. This is very easy to reverse, and can be used to create
25
+ custom movesets externally without the need for Roblox or JJS.
26
+
27
+ Decoding a code with base64 and zstd gives the original JSON. From there, a
28
+ script can modify the JSON to create a custom moveset.
29
+ </details>
30
+
31
+ ## Usage
32
+
33
+ First, install the library using `npm install @dnd-ed/jsshenanigans`.
34
+
35
+ Then, in a JavaScript file, import the library as `jss` and create a character:
36
+
37
+ ```js
38
+ import * as jss from "@dnd-ed/jsshenanigans";
39
+
40
+ const character = new jss.Character();
41
+ ```
42
+
43
+ From here, you can create skills using `character.create.skill()`.
44
+
45
+ ```js
46
+ character.create.skill("Super Cool Skill", { cooldown: 5 });
47
+ ```
48
+
49
+ Nodes live in their own module, so import them too:
50
+
51
+ ```js
52
+ import * as nodes from "@dnd-ed/jsshenanigans/nodes";
53
+
54
+ character.create.skill("Punch", [nodes.HITBOX({ damage: 5 })]);
55
+ ```
56
+
57
+ Check out `demo/demo.js` for a full example.
58
+
59
+ ## TypeScript
60
+
61
+ The library ships type declarations, so TypeScript and editors with a language
62
+ server get full autocomplete for every builder.
63
+
64
+ ## Features
65
+
66
+ - [x] Support for every documented node, condition and property, including
67
+ `PARTICLE`, `LOOK` and `SETMELEE`
68
+ - [x] Support for all skill types
69
+ - [x] Exports as a JJS-valid character code
70
+ - I recommend you paste it into JJS to check if it's working, then copy the character block's export
71
+ - [x] Branch support
72
+ - [x] Variable names for animations, easing styles/directions, effects, etc
73
+ - [ ] Custom nodes
74
+ - [ ] Domain node
75
+ - [ ] Fake rigs
76
+ - [ ] Fake rig animations
77
+
78
+ ## Requirements
79
+
80
+ Node.js **22.15+** (it ships `zstd` in `node:zlib`). No required runtime
81
+ dependencies.
82
+
83
+ ## zstd backends
84
+
85
+ The codec picks a backend automatically:
86
+
87
+ 1. `node:zlib` --- the default, native, and the only one that can compress.
88
+ 2. [`fzstd`](https://www.npmjs.com/package/fzstd) --- an optional, pure-JS
89
+ fallback. It can only *decompress*, so it is used for reading codes when
90
+ `node:zlib` is unavailable.
91
+
92
+ Set `JSSHENANIGANS_ZSTD_BACKEND` (e.g. to `"fzstd"`) to prefer a specific one.
93
+ Run `npm run bench` to compare the installed backends; `node:zlib` is several
94
+ times faster, which is why it stays the default.
95
+
96
+ ## License
97
+
98
+ MIT. See `LICENSE` and `NOTICE.md`.
package/package.json CHANGED
@@ -1,6 +1,114 @@
1
1
  {
2
2
  "name": "@dnd-ed/jsshenanigans",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.1.1",
4
+ "description": "A JavaScript library for creating, loading and modifying Jujutsu Shenanigans movesets.",
5
+ "keywords": [
6
+ "jujutsu",
7
+ "shenanigans",
8
+ "jjs",
9
+ "moveset",
10
+ "roblox"
11
+ ],
12
+ "license": "MIT",
13
+ "author": "akinari (aki) <pts@itzdanti.dev>",
14
+ "type": "module",
15
+ "main": "./src/index.js",
16
+ "types": "./src/index.d.ts",
17
+ "exports": {
18
+ ".": {
19
+ "types": "./src/index.d.ts",
20
+ "default": "./src/index.js"
21
+ },
22
+ "./nodes": {
23
+ "types": "./src/nodes.d.ts",
24
+ "default": "./src/nodes.js"
25
+ },
26
+ "./conditions": {
27
+ "types": "./src/conditions.d.ts",
28
+ "default": "./src/conditions.js"
29
+ },
30
+ "./codec": {
31
+ "types": "./src/codec.d.ts",
32
+ "default": "./src/codec.js"
33
+ },
34
+ "./types": {
35
+ "types": "./src/types.d.ts",
36
+ "default": "./src/types.js"
37
+ },
38
+ "./tools": {
39
+ "types": "./src/tools.d.ts",
40
+ "default": "./src/tools.js"
41
+ },
42
+ "./defaults": {
43
+ "types": "./src/defaults.d.ts",
44
+ "default": "./src/defaults.js"
45
+ },
46
+ "./package.json": "./package.json"
47
+ },
48
+ "typesVersions": {
49
+ "*": {
50
+ "nodes": [
51
+ "./src/nodes.d.ts"
52
+ ],
53
+ "conditions": [
54
+ "./src/conditions.d.ts"
55
+ ],
56
+ "codec": [
57
+ "./src/codec.d.ts"
58
+ ],
59
+ "types": [
60
+ "./src/types.d.ts"
61
+ ],
62
+ "tools": [
63
+ "./src/tools.d.ts"
64
+ ],
65
+ "defaults": [
66
+ "./src/defaults.d.ts"
67
+ ],
68
+ "*": [
69
+ "./src/index.d.ts"
70
+ ]
71
+ }
72
+ },
73
+ "files": [
74
+ "src",
75
+ "README.md",
76
+ "LICENSE",
77
+ "NOTICE.md"
78
+ ],
79
+ "engines": {
80
+ "node": ">=22.15.0"
81
+ },
82
+ "scripts": {
83
+ "test": "node --test",
84
+ "test:coverage": "node --test --experimental-test-coverage",
85
+ "lint": "eslint .",
86
+ "typecheck": "tsc -p tsconfig.json",
87
+ "bench": "node scripts/bench-backends.js",
88
+ "demo": "node demo/demo.js"
89
+ },
90
+ "devDependencies": {
91
+ "eslint": "^9.0.0",
92
+ "typescript": "^7.0.2"
93
+ },
94
+ "optionalDependencies": {
95
+ "fzstd": "^0.1.1"
96
+ },
97
+ "publishConfig": {
98
+ "access": "public"
99
+ },
100
+ "repository": {
101
+ "type": "git",
102
+ "url": "git+https://github.com/dnd-ed/jsshenanigans.git"
103
+ },
104
+ "homepage": "https://github.com/dnd-ed/jsshenanigans",
105
+ "bugs": {
106
+ "url": "https://github.com/dnd-ed/jsshenanigans/issues"
107
+ },
108
+ "contributors": [
109
+ {
110
+ "name": "akinari (aki)",
111
+ "email": "pts@itzdanti.dev"
112
+ }
113
+ ]
114
+ }
@@ -0,0 +1,82 @@
1
+ import type { Node } from "./nodes.js";
2
+ import type { BranchDefinition } from "./utils.js";
3
+
4
+ export type SkillKind = "SKILL" | "SPECIAL" | "MELEE" | "CHASE" | "AWAKENING";
5
+
6
+ export interface Skill {
7
+ NAME?: string;
8
+ K_NAME?: string;
9
+ KEY?: number;
10
+ DATA?: string;
11
+ [key: string]: unknown;
12
+ }
13
+
14
+ export interface SkillOptions {
15
+ /** The skill's node list (also accepted as the second positional argument). */
16
+ line?: Node[];
17
+ kind?: SkillKind;
18
+ cooldown?: number | null;
19
+ key?: number | null;
20
+ add?: boolean;
21
+ duration?: number | null;
22
+ delay?: number | null;
23
+ properties?: Record<string, number | boolean | string> | null;
24
+ conditions?: Array<Record<string, unknown>> | null;
25
+ branches?: Record<string, BranchDefinition> | null;
26
+ tooltip?: string | null;
27
+ color?: string | null;
28
+ extra?: Record<string, unknown> | null;
29
+ }
30
+
31
+ export interface SkillSummary {
32
+ kind: string | undefined;
33
+ name: string | undefined;
34
+ }
35
+
36
+ export interface CharacterOptions {
37
+ hide_character_extras?: boolean;
38
+ raw?: unknown[] | null;
39
+ }
40
+
41
+ export declare class CreateHelper {
42
+ character: Character;
43
+ /** Create a skill, with the node list as the second argument. */
44
+ skill(name: string, line?: Node[], options?: SkillOptions): void;
45
+ /** Create a skill, with the node list inside `options.line`. */
46
+ skill(name: string, options?: SkillOptions): void;
47
+ }
48
+
49
+ export declare class Character {
50
+ raw: Skill[];
51
+ create: CreateHelper;
52
+
53
+ constructor(options?: CharacterOptions);
54
+
55
+ /** Load a character from a JJS character code. Fields are kept verbatim. */
56
+ static from_code(code: string): Character;
57
+
58
+ /** Load a character from a raw JSON string (the inner a code holds). */
59
+ static from_raw(rawJson: string): Character;
60
+
61
+ /** Append a raw skill object, checked shallowly. */
62
+ create_raw_skill(skill: Skill): void;
63
+
64
+ /** Export the character as a raw JSON string. */
65
+ export_raw(): string;
66
+
67
+ /** Export the character as a JJS-compatible character code. */
68
+ export_character_code(): string;
69
+
70
+ /** Alias for `export_character_code`. */
71
+ to_code(): string;
72
+
73
+ get length(): number;
74
+
75
+ [Symbol.iterator](): IterableIterator<Skill>;
76
+
77
+ /** A list of `{ kind, name }` for every entry, in order. */
78
+ get skills(): SkillSummary[];
79
+
80
+ _used_keys(): Set<number>;
81
+ _next_key(): number;
82
+ }