@sandustry-modding/types 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.4.0 - 2026-08-29
+
+https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.4.0
+
+### Added
+
+- `npm run release` script: changelog/registry/auth checks, `validate`, then `npm publish` (optional `--dry-run`)
+- `src/configs/` types for `modinfo.json` and `patches.json` (`@sandustry-modding/types/configs`), with JSDoc on every key
+- Stronger structure definition fields: `tooltipHover`, `spanTiles`, `linkedClearance`, spritesheet/ui render blocks
+- Stronger `TechDefinition` fields used by tech nodes (`cost`, `unlocks`, `currencyType`, `branch`)
+- JSDoc `@example` blocks on many Sandkit members (main, worker, and configs)
+- Prebuilt Docsify search index (`docs/assets/search-index.js`) so API search works without a runtime crawl
+- Nested namespace roots in the docs sidebar (`sandkit`, `sandkit.api`, worker, engine, react)
+
+### Changed
+
+- Official `@see` links use a short “Official docs” label that deep-links to Sandkit HTML sections
+- Docs search ranks full runtime paths (`sandkit.api.settings.get()`) instead of local member names only
+- Move Full API reference to the bottom of the docs root nav block
+- Drop the page TOC plugin and the nested `docs/api/_sidebar.md` in favor of one site sidebar
+
+## 0.3.1 - 2026-08-27
+
+https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.3.1
+
+
+
+### Fixed
+
+- Deep package imports such as `@sandustry-modding/types/sandkit/engine` (Node `exports` `*` matches one path segment; map file and `index.d.ts` targets under `src/`)
+- Ship root `CHANGELOG.md` and `LICENSE` in the npm tarball
+- Document ambient setup with `/// <reference types="@sandustry-modding/types" />` (do not list this package under `compilerOptions.types`)
+
+### Added
+
+- `npm run validate` gate: declaration typecheck, unit tests, and packed-tarball consumer probes
+
+## 0.3.0 - 2026-08-27
+
+https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.3.0
+
+### Changed
+
+- Move declaration sources into `src/` (`src/sandkit`, `src/worker`, `src/shared`, `src/global.d.ts`). Package subpaths such as `@sandustry-modding/types/sandkit/engine` stay the same
+- Show local names for API member headings in the Docsify reference (full runtime path stays under each heading)
+
+## 0.2.0 - 2026-08-27
+
+https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.2.0
+
+### Added
+
+- Official Sandkit API coverage from [sandustry.com/sandkit.html](https://sandustry.com/sandkit.html): `api.entities`, `api.pipes`, `api.factory`, `api.game`, `api.blueprints`, `api.pickups`, `api.grid.mutate`, and related worker surfaces
+- JSDoc `@see` links back to the official Sandkit page on documented members
+
+### Changed
+
+- Canonical mutation names match official docs (`createAtCell`, `grid.mutate`, `getTypeById`, and similar). Old names stay as `@deprecated` aliases (`*WhenIdle`, `api.world`, `getTypeFromId`, and similar)
+
+## 0.1.1 - 2026-08-27
+
+https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.1.1
+
+### Changed
+
+- Export subpaths (`./*`) so mods can import declaration modules such as `@sandustry-modding/types/sandkit/engine`
+
+## 0.1.0 - 2026-08-27
+
+https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.1.0
+
+### Added
+
+- Initial public release of `@sandustry-modding/types`
+- TypeScript declarations for main-thread `sandkit` (`sandkit/api`, `sandkit/engine`, `sandkit/enums`, `sandkit/react`)
+- Worker-thread declarations under `worker/` (`WorkerSandkitApi`)
+- Shared base shapes under `shared/` for main and worker reuse
+- Ambient `sandkit` free variable and type aliases via `global.d.ts`
+- Docsify API reference generated from the declarations

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sandustry-modding
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -19,6 +19,7 @@ Folder layout mirrors runtime shape so you can jump from code to the matching `.
 | `src/global.d.ts` | Ambient `sandkit` free variable and type aliases |
 | `src/worker/` | Worker-thread `sandkit.api` (see `WorkerSandkitApi`) |
 | `src/shared/` | Internal base shapes reused by main and worker declarations |
+| `src/configs/` | `modinfo.json` / `patches.json` schemas (not a runtime object) |
 
 ## Runtime shape vs `export namespace`
 
@@ -37,36 +38,23 @@ Declaration files use `export namespace` because it is the usual `.d.ts` pattern
 npm install @sandustry-modding/types
 ```
 
-### Project config (preferred)
+### Ambient types (preferred)
 
-Add the package to `compilerOptions.types` in `tsconfig.json` or `jsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "types": ["@sandustry-modding/types"]
-  }
-}
-```
-
-If you already list other packages in `types` (for example `"react"` or `"node"`), keep those entries and add `"@sandustry-modding/types"` to the same array. A non-empty `types` list replaces TypeScript’s default auto-inclusion of all `@types/*` packages.
-
-`jsconfig.json` uses the same shape for JavaScript mods.
-
-### Per-file reference
-
-You can also pull the ambient types into one file:
+Pull the host `sandkit` ambient into your project with a triple-slash reference. Put it at the top of `main.js` / `worker.js`, or in a small ambient `.d.ts` that your `tsconfig` / `jsconfig` includes:
 
 ```ts
 /// <reference types="@sandustry-modding/types" />
 ```
 
-That triple-slash directive works in `.ts` and `.js` (including checked JS with `checkJs`). Put it at the top of `main.js` / `worker.js`, or in a small ambient `.d.ts` included by your project.
+That works in `.ts` and `.js` (including checked JS with `checkJs`).
+
+Do **not** list `@sandustry-modding/types` under `compilerOptions.types`. That list only loads packages from `node_modules/@types` (for example `"react"` or `"node"`).
 
 Deep declaration modules are also available, for example:
 
 ```ts
 import type { RetroConsoleGame } from "@sandustry-modding/types/sandkit/engine";
+import type { ModInfo, BundlePatch } from "@sandustry-modding/types/configs";
 ```
 
 ## Usage
@@ -74,6 +62,7 @@ import type { RetroConsoleGame } from "@sandustry-modding/types/sandkit/engine";
 - **Main mod (`main.js`):** use the ambient free name `sandkit`. Type aliases such as `SandkitApi` are global; do not import a value binding.
 - **Worker mod (`worker.js`):** type `sandkit.api` as `WorkerSandkitApi`. Worker and main APIs overlap but are not interchangeable.
 - **Shared folder:** not a runtime namespace. It holds domain shapes and API bases that main and worker modules extend.
+- **Configs folder:** `modinfo.json` and `patches.json` schemas (`@sandustry-modding/types/configs`). Not part of the live `sandkit` object.
 
 ## Maintaining types
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandustry-modding/types",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "TypeScript declarations and API docs for the Sandustry Sandkit host API",
   "license": "MIT",
   "repository": {
@@ -17,14 +17,70 @@
       "types": "./src/global.d.ts"
     },
     "./package.json": "./package.json",
-    "./*": {
-      "types": "./src/*"
+    "./sandkit": {
+      "types": "./src/sandkit/index.d.ts"
+    },
+    "./sandkit/*": {
+      "types": [
+        "./src/sandkit/*.d.ts",
+        "./src/sandkit/*/index.d.ts"
+      ]
+    },
+    "./sandkit/*/*": {
+      "types": [
+        "./src/sandkit/*/*.d.ts",
+        "./src/sandkit/*/*/index.d.ts"
+      ]
+    },
+    "./sandkit/*/*/*": {
+      "types": [
+        "./src/sandkit/*/*/*.d.ts",
+        "./src/sandkit/*/*/*/index.d.ts"
+      ]
+    },
+    "./shared": {
+      "types": "./src/shared/index.d.ts"
+    },
+    "./shared/*": {
+      "types": [
+        "./src/shared/*.d.ts",
+        "./src/shared/*/index.d.ts"
+      ]
+    },
+    "./shared/*/*": {
+      "types": [
+        "./src/shared/*/*.d.ts",
+        "./src/shared/*/*/index.d.ts"
+      ]
+    },
+    "./worker": {
+      "types": "./src/worker/index.d.ts"
+    },
+    "./worker/*": {
+      "types": [
+        "./src/worker/*.d.ts",
+        "./src/worker/*/index.d.ts"
+      ]
+    },
+    "./worker/*/*": {
+      "types": [
+        "./src/worker/*/*.d.ts",
+        "./src/worker/*/*/index.d.ts"
+      ]
+    },
+    "./configs": {
+      "types": "./src/configs/index.d.ts"
+    },
+    "./configs/*": {
+      "types": [
+        "./src/configs/*.d.ts",
+        "./src/configs/*/index.d.ts"
+      ]
     }
   },
   "files": [
     "src/**/*.d.ts",
     "CHANGELOG.md",
-    "docs/Changelog.md",
     "LICENSE",
     "README.md"
   ],
@@ -33,7 +89,11 @@
     "docs:api": "node scripts/generate-api-docs.mjs",
     "docs:serve": "npx --yes docsify-cli serve docs",
     "test": "node --test scripts/api-search.test.js",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "verify-package": "node scripts/verify-package.mjs",
+    "validate": "npm run typecheck && npm test && npm run verify-package",
+    "prepack": "npm run validate",
+    "release": "node scripts/publish.mjs"
   },
   "devDependencies": {
     "@types/react": "^18.3.1",

package/src/configs/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Sandkit mod file schemas: `modinfo.json` and `patches.json`.
+ *
+ * These are not runtime `sandkit` properties. Import from
+ * `@sandustry-modding/types/configs` when typing mod folder config files.
+ *
+ * @module
+ *
+ * @see [Official docs](https://sandustry.com/sandkit.html#mod-files-heading)
+ */
+
+export type {
+  ConfigSchemaBoolean,
+  ConfigSchemaChoice,
+  ConfigSchemaChoiceOption,
+  ConfigSchemaEntry,
+  ConfigSchemaNumber,
+  ModGameVersion,
+  ModInfo,
+  ModMapBlueprints,
+  ModMapColorMapping,
+  ModMapColorMappingLayers,
+  ModMapDefinition,
+  ModMapDepthLight,
+  ModMapParallax,
+  ModMapPoint,
+  ModMapTopBounds,
+  ModProvide,
+  TextureOverride,
+} from "./modinfo";
+
+export type {
+  BundlePatch,
+  BundlePatchRegex,
+  BundlePatchesFile,
+  PatchOperation,
+  PatchTargetFile,
+} from "./patches";