@wildware/smart-fellas 0.0.0-stage → 1.8.0

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.
Files changed (5) hide show
  1. package/CHANGELOG.md +107 -0
  2. package/LICENSE +21 -0
  3. package/README.md +142 -2
  4. package/package.json +35 -4
  5. package/smart-fellas.d.ts +1057 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,107 @@
1
+ # Changelog
2
+
3
+ What changed in the Smart Fellas scripting API, its examples and its wiki, newest first.
4
+
5
+ ## 1.8.0
6
+
7
+ Calls added; scripts written for 1.0.0 to 1.7.0 work as they did. Each needs a game that knows API
8
+ 1.8.0.
9
+
10
+ - Invisible players: `player.setInvisible(true)` hides a player from everyone else (no other PC is
11
+ sent their body), and `player.invisible` reads it on the host.
12
+ - Wiki: an example on Players.
13
+
14
+ ## 1.7.0
15
+
16
+ Calls added; scripts written for 1.0.0 to 1.6.0 work as they did. Each needs a game that knows API
17
+ 1.7.0.
18
+
19
+ - Bot levels: `player.setBotLevel(level)` makes one bot play `"easy"`, `"normal"` or `"hard"` from
20
+ now on (a new type, `BotLevel`), and `player.botLevel` reads it on the host.
21
+ - Wiki: the bots example on Game modes sets levels.
22
+
23
+ ## 1.6.0
24
+
25
+ Calls added; scripts written for 1.0.0 to 1.5.0 work as they did. Each needs a game that knows API
26
+ 1.6.0.
27
+
28
+ - Markers on players: `MarkerSpec` takes `on: player` in place of `at`, and the marker rides over
29
+ them. A screen shows it only while it is sent that player's body.
30
+ - The objects a call takes (a marker's, a widget's, a menu's, the water's, a light's, a team's, an
31
+ ability's, and points) are read for the values they hold themselves. A value that comes from a
32
+ getter, from the object's prototype or through a `Proxy` reads as left out, and a script's own code
33
+ never runs inside a call. Object literals and `Vec` points work as before.
34
+ - Wiki: an example on HUD widgets and markers.
35
+
36
+ ## 1.5.0
37
+
38
+ Calls added; scripts written for 1.0.0 to 1.4.0 work as they did. Each needs a game that knows API
39
+ 1.5.0.
40
+
41
+ - The water: `game.setWater(spec, seconds?)` changes its colour, how far anyone sees through it and
42
+ how bright it is, fading in over the seconds given (a new type, `WaterSpec`);
43
+ `game.resetWater(seconds?)` gives back the map's own.
44
+ - Lights: `game.light(id, spec)` puts up a coloured light in the world, or moves or changes it (a
45
+ new type, `LightSpec`); `game.removeLight(id)` takes it down. At most 16 at once.
46
+ - Wiki: a new page, Water and lights, with examples.
47
+
48
+ ## 1.4.0
49
+
50
+ Calls added; scripts written for 1.0.0 to 1.3.0 work as they did. Each needs a game that knows API
51
+ 1.4.0.
52
+
53
+ - Menus: `game.menu(id, spec, viewers?)` opens a card of 2 to 5 choices (a new type, `MenuSpec`)
54
+ that players pick with the number keys 1 to 5; `game.removeMenu(id, viewers?)` closes it.
55
+ - `game.onChoose(handler)` hears each pick: the player, the menu's id, the choice's place and its
56
+ text.
57
+ - `game.vote(spec, viewers?)` asks a question as a menu and settles with how it came out (new types,
58
+ `VoteSpec` and `VoteResult`).
59
+ - `game.endRound(winner, why?, text?)` takes the script's own line for the results; `why` may be
60
+ `null`.
61
+ - Wiki: a new page, Menus and votes, with examples.
62
+
63
+ ## 1.3.0
64
+
65
+ Calls added; scripts written for 1.0.0 to 1.2.0 work as they did. Each needs a game that knows API
66
+ 1.3.0.
67
+
68
+ - Rays through the map: `game.raycast(from, to)` settles with where a straight line first meets the
69
+ map's rock, sand or pieces (a new type, `RayHit`), or null. Players and creatures are let through.
70
+ - Built on it: `game.lineOfSight(a, b)` and `game.groundBelow(point)`.
71
+ - `game.playArea`: the box players swim in (a new type, `PlayArea`).
72
+ - Wiki: a new page, Rays and the ground, with examples.
73
+
74
+ ## 1.2.0
75
+
76
+ Calls added; scripts written for 1.0.0 and 1.1.0 work as they did. Each needs a game that knows API
77
+ 1.2.0.
78
+
79
+ - `player.allow(skill, allowed)` switches one player's dash, ink, grab, smell or gun off, or back
80
+ on, until the round ends; `player.allowed(skill)` reads it back. A new type, `Skill`, names them.
81
+ - `player.data`: a store of values for one player, kept from round to round for the whole match.
82
+ The store's calls now have a type of their own, `Store`.
83
+ - Wiki: the Players page explains both, with examples.
84
+
85
+ ## 1.1.0
86
+
87
+ Calls added; scripts written for 1.0.0 work as they did. Each needs a game that knows API 1.1.0.
88
+
89
+ - Helpers in every script: `Vec` (maths on points), `Maths` (clamp, lerp, remap and more), `Random`
90
+ (random numbers from a seed, the same on every PC), `Ease` and `tween` (smooth movement over
91
+ time), `StateMachine` (named phases, one at a time), `store` (values for this round, emptied as
92
+ each round starts) and `log` (a line in the game's log).
93
+ - Finding things near a point: `game.playersNear`, `game.nearestPlayer`, `game.creaturesNear` and
94
+ `game.nearestCreature`.
95
+ - On screen, for everyone, one team or one player: `game.announce` (big text in the middle),
96
+ `game.widget` and `game.removeWidget` (text, bars, counters and countdowns on the left), and
97
+ `game.marker` and `game.removeMarker` (markers in the world, seen through rock).
98
+ - For one player: `player.setSpeed` and `player.speed`, `player.playSound` and `player.announce`.
99
+ - `game.playSoundForTeam`: a sound for one team only.
100
+ - New events: `game.onDash`, `game.onInk`, `game.onGrab` and `game.onShoot`.
101
+ - A new example mode, King of the Reef (`examples/showcase_mode`), that uses most of the above.
102
+ - Wiki: new pages Helpers, Finding things, and HUD widgets and markers; a Helpers reference page.
103
+
104
+ ## 1.0.0
105
+
106
+ - The scripting API for Smart Fellas maps and game modes in a repository of its own: the types file,
107
+ the map script examples, the game mode template and the wiki.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Wildware Studios
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,143 @@
1
- # Temporary Holding Version
1
+ # Smart Fellas modding
2
2
 
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.
3
+ The scripting API for [Smart Fellas](https://wildwarestudios.com/games/smart-fellas) maps and game
4
+ modes: the TypeScript types, worked examples, a game mode to start from, and
5
+ **[the modding wiki](https://github.com/wildware-uk/smart-fellas-modding/wiki)**.
6
+
7
+ ## What you can make
8
+
9
+ - **Map scripts.** Make a map do things its pieces can't: a lever opens a door, a cave floods near
10
+ the end of the round, eating a treasure wakes a shark. You build maps in Godot with the free
11
+ [map maker](https://github.com/wildware-uk/smart-fellas-map-maker).
12
+ - **Game modes.** Set a match's rules: the teams (even new ones, playing as sharks), what a catch
13
+ does, the scores, the clock, the bots, and who wins. Any mode plays on any map.
14
+
15
+ Both are written in TypeScript (or plain JavaScript), run in a sealed box on every PC, and are shared
16
+ on the Steam Workshop.
17
+
18
+ ## Quick start
19
+
20
+ 1. In the game, open **Workshop > Modes > My modes** and press **Open modes folder**.
21
+ 2. Copy the [`mode_template`](mode_template) folder into it, and rename the copy.
22
+ 3. Copy [`smart-fellas.d.ts`](smart-fellas.d.ts) and [`tsconfig.json`](tsconfig.json) into its
23
+ `scripts/` folder, and open that folder in
24
+ [VS Code](https://code.visualstudio.com): every call now completes as you type. (Or install the
25
+ types with npm instead: see [Install with npm](#install-with-npm).)
26
+ 4. Change `scripts/mode.ts`. Here's a whole mode:
27
+
28
+ ```ts
29
+ // Hot potato: every 20 seconds, the diver with the fewest catches is out of luck: they swap sides.
30
+ game.onMatchStart(() => {
31
+ game.scoreboard("Catches");
32
+ });
33
+
34
+ game.onCaught((_octopus, by) => {
35
+ if (by) {
36
+ by.addScore(1);
37
+ by.setCell("Catches", by.score + 1);
38
+ }
39
+ });
40
+
41
+ every(20, () => {
42
+ if (game.phase !== "play") {
43
+ return;
44
+ }
45
+ const divers = game.players().filter((player) => player.team === "diver" && player.alive);
46
+ divers.sort((a, b) => a.score - b.score);
47
+ const unlucky = divers[0];
48
+ if (unlucky && divers.length > 1) {
49
+ unlucky.setTeam("octopus");
50
+ game.say(`${unlucky.name} was too slow, and swims with the octopuses now!`);
51
+ }
52
+ });
53
+
54
+ game.onTimeUp(() => {
55
+ game.endRound("octopus", "timeUp");
56
+ });
57
+ ```
58
+
59
+ 5. Host a game on any map and pick your mode under **Game mode** in the lobby.
60
+
61
+ For a map script, the map maker puts the types file into your map's scripts folder for you. The
62
+ wiki's [Getting started](https://github.com/wildware-uk/smart-fellas-modding/wiki/Getting-Started)
63
+ walks through both.
64
+
65
+ ## Install with npm
66
+
67
+ If you use [Node](https://nodejs.org), you can install the types as a package rather than copying the
68
+ file:
69
+ [`@wildware/smart-fellas`](https://www.npmjs.com/package/@wildware/smart-fellas). In your mode's
70
+ `scripts/` folder, copy [`tsconfig.json`](tsconfig.json) in, then run
71
+
72
+ ```
73
+ npm install --save-dev @wildware/smart-fellas
74
+ ```
75
+
76
+ and add one line to the `compilerOptions` in its `tsconfig.json`:
77
+
78
+ ```json
79
+ "types": ["@wildware/smart-fellas"]
80
+ ```
81
+
82
+ Then `npm update` gets the newest types. Each release here is published to npm at the same version.
83
+ The game never reads `node_modules`, and the Workshop doesn't upload it. You don't need npm at all:
84
+ copying the file works just as well. A map doesn't need it either: the map maker puts the types file
85
+ in its scripts folder for you.
86
+
87
+ ## What's here
88
+
89
+ | | |
90
+ | --- | --- |
91
+ | [`smart-fellas.d.ts`](smart-fellas.d.ts) | every call a script can make, with what it does (also on npm as `@wildware/smart-fellas`) |
92
+ | [`tsconfig.json`](tsconfig.json) | the editor settings to put beside your scripts |
93
+ | [`examples/`](examples) | three map scripts to copy (a lever and door, a flooding cave, a treasure that wakes a shark), and a whole game mode, [King of the Reef](examples/showcase_mode), that shows off the helpers and the HUD |
94
+ | [`mode_template/`](mode_template) | a small working game mode, Catch Count, to make your own |
95
+ | [`wiki/`](wiki) | the wiki's pages, copied to [the wiki](https://github.com/wildware-uk/smart-fellas-modding/wiki) |
96
+ | [`tools/`](tools) | the checks below |
97
+
98
+ ## The wiki
99
+
100
+ - [Getting started](https://github.com/wildware-uk/smart-fellas-modding/wiki/Getting-Started) and
101
+ [How scripts run](https://github.com/wildware-uk/smart-fellas-modding/wiki/How-Scripts-Run)
102
+ - [Map scripts](https://github.com/wildware-uk/smart-fellas-modding/wiki/Map-Scripts) and
103
+ [Game modes](https://github.com/wildware-uk/smart-fellas-modding/wiki/Game-Modes)
104
+ - [Players](https://github.com/wildware-uk/smart-fellas-modding/wiki/Players),
105
+ [Events](https://github.com/wildware-uk/smart-fellas-modding/wiki/Events),
106
+ [Timers](https://github.com/wildware-uk/smart-fellas-modding/wiki/Timers),
107
+ [Creatures](https://github.com/wildware-uk/smart-fellas-modding/wiki/Creatures),
108
+ [Sounds](https://github.com/wildware-uk/smart-fellas-modding/wiki/Sounds),
109
+ [Messages and HUD](https://github.com/wildware-uk/smart-fellas-modding/wiki/Messages-and-HUD),
110
+ [HUD widgets and markers](https://github.com/wildware-uk/smart-fellas-modding/wiki/HUD-Widgets-and-Markers),
111
+ [Finding things](https://github.com/wildware-uk/smart-fellas-modding/wiki/Finding-Things),
112
+ [Rays and the ground](https://github.com/wildware-uk/smart-fellas-modding/wiki/Rays-and-Ground) and
113
+ [Helpers](https://github.com/wildware-uk/smart-fellas-modding/wiki/Helpers)
114
+ - [Testing and publishing](https://github.com/wildware-uk/smart-fellas-modding/wiki/Testing-and-Publishing),
115
+ [Common mistakes](https://github.com/wildware-uk/smart-fellas-modding/wiki/Common-Mistakes) and the
116
+ [FAQ](https://github.com/wildware-uk/smart-fellas-modding/wiki/FAQ)
117
+ - The [Reference](https://github.com/wildware-uk/smart-fellas-modding/wiki/Reference): every call,
118
+ made from the types file
119
+
120
+ ## Every example is checked
121
+
122
+ `npm ci && npm run check` type-checks every example here against the types: the map scripts, the mode
123
+ template, the example mode, and every code block in this README and the wiki. It also checks the wiki's reference pages
124
+ still match the types file. It runs on every change to this repository.
125
+
126
+ ## Where this comes from
127
+
128
+ This is the API's own home: the game and the map maker take their copy of it from here, pinned to a
129
+ release. Bug reports and ideas are very welcome:
130
+ [open an issue](https://github.com/wildware-uk/smart-fellas-modding/issues/new). The API itself is
131
+ what the game understands, so a new call needs the game to learn it first; ask for it in an issue. For
132
+ help, and to show off what you made, come to the Smart Fellas Discord, linked from
133
+ [the map guide](https://wildwarestudios.com/games/smart-fellas/maps).
134
+
135
+ Every version, and what changed in it, is on the
136
+ [releases page](https://github.com/wildware-uk/smart-fellas-modding/releases) and in
137
+ [CHANGELOG.md](CHANGELOG.md).
138
+
139
+ ## Licence
140
+
141
+ MIT: see [LICENSE](LICENSE). Use it, copy it, change it, in your maps and modes or anywhere else.
142
+
143
+ Smart Fellas modding, by [Wildware Studios](https://wildwarestudios.com).
package/package.json CHANGED
@@ -1,6 +1,37 @@
1
1
  {
2
2
  "name": "@wildware/smart-fellas",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.8.0",
4
+ "description": "TypeScript types for Smart Fellas map scripts and game modes: every call a script can make, with what it does.",
5
+ "license": "MIT",
6
+ "author": "Wildware Studios (https://wildwarestudios.com)",
7
+ "homepage": "https://github.com/wildware-uk/smart-fellas-modding/wiki",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/wildware-uk/smart-fellas-modding.git"
11
+ },
12
+ "bugs": "https://github.com/wildware-uk/smart-fellas-modding/issues",
13
+ "keywords": [
14
+ "smart-fellas",
15
+ "modding",
16
+ "typescript",
17
+ "types",
18
+ "game-mode",
19
+ "steam-workshop"
20
+ ],
21
+ "type": "module",
22
+ "types": "smart-fellas.d.ts",
23
+ "files": [
24
+ "smart-fellas.d.ts",
25
+ "CHANGELOG.md"
26
+ ],
27
+ "publishConfig": {
28
+ "access": "public"
29
+ },
30
+ "scripts": {
31
+ "check": "node tools/check.mjs",
32
+ "reference": "node tools/reference.mjs"
33
+ },
34
+ "devDependencies": {
35
+ "typescript": "6.0.3"
36
+ }
37
+ }