{"id":32516203,"url":"https://github.com/stationeers-ic/exact-ic10-math","last_synced_at":"2025-10-28T01:20:20.537Z","repository":{"id":237070445,"uuid":"786056924","full_name":"Stationeers-ic/exact-ic10-math","owner":"Stationeers-ic","description":"Bitwise Operations in TypeScript (JavaScript) for Stationeers","archived":false,"fork":false,"pushed_at":"2025-10-25T13:47:46.000Z","size":147,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-25T15:25:57.851Z","etag":null,"topics":["bitwise-operators","csharp","typescript"],"latest_commit_sha":null,"homepage":"https://ic10.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Stationeers-ic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-04-13T09:45:17.000Z","updated_at":"2025-10-25T13:47:49.000Z","dependencies_parsed_at":"2024-04-29T20:58:59.359Z","dependency_job_id":"4c1f9bbb-bf7b-487f-8aed-08e77efe89f7","html_url":"https://github.com/Stationeers-ic/exact-ic10-math","commit_stats":null,"previous_names":["stationeers-ic/stationeers-bitwise-functions"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Stationeers-ic/exact-ic10-math","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stationeers-ic%2Fexact-ic10-math","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stationeers-ic%2Fexact-ic10-math/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stationeers-ic%2Fexact-ic10-math/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stationeers-ic%2Fexact-ic10-math/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Stationeers-ic","download_url":"https://codeload.github.com/Stationeers-ic/exact-ic10-math/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stationeers-ic%2Fexact-ic10-math/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281368644,"owners_count":26489047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-27T02:00:05.855Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitwise-operators","csharp","typescript"],"created_at":"2025-10-28T01:20:19.747Z","updated_at":"2025-10-28T01:20:20.532Z","avatar_url":"https://github.com/Stationeers-ic.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e # @stationeers-ic/exact-ic10-math\n\u003e\n\u003e [![bundle size](https://badgen.net/bundlephobia/minzip/@stationeers-ic/exact-ic10-math) ![tree shaking](https://badgen.net/bundlephobia/tree-shaking/@stationeers-ic/exact-ic10-math) ![dependency count](https://badgen.net/bundlephobia/dependency-count/@stationeers-ic/exact-ic10-math)](https://bundlephobia.com/package/@stationeers-ic/exact-ic10-math)\n\nA library that faithfully implements IC10 math, bitwise, and logic instructions for Stationeers as TypeScript / JavaScript functions. The core goal is to mimic the game's IC10 instruction semantics exactly — including operand orders, bit widths, wrapping behavior, and edge-case results — and to provide clear usage instructions so the functions behave like the in-game instructions.\n\n## Features\n\n**TL;DR** — what this library provides:\n\n-   Faithful IC10 math ops (add, sub, mul, div, pow, etc.) with in-game edge-case semantics\n-   Bitwise and field operations (and, or, xor, sll/srl, ins/extr, etc.) matching IC10 behavior\n-   CRC32 / string hashing that matches the game's hash function (`hashString`) for device names\n-   Deterministic PRNG matching the game's `Random` behavior plus convenience `rand` helpers\n-   ASCII packing helpers: `PackAscii6` and `UnpackAscii6` for packing up to 6 ASCII chars into a number\n-   ESM and named exports usable in TypeScript and Node/Browser builds\n\n## Installation\n\n```bash\nnpm install @stationeers-ic/exact-ic10-math\n# or\nbun add @stationeers-ic/exact-ic10-math\n```\n\n## Usage\n\n### Default import\n\nQuickest way to get started:\n\n```ts\nimport ic10 from \"@stationeers-ic/exact-ic10-math\"\n\n// basic math\nconsole.log(ic10.add(2, 3)) // 5\nconsole.log(ic10.mul(4, 5)) // 20\nconsole.log(ic10.abs(-7)) // 7\nconsole.log(ic10.round(2.5)) // 2\n\n// bitwise / fields\nconsole.log(ic10.and(5, 3)) // 1\nconsole.log(ic10.ins(0, 1, 2, 3)) // 6\n```\n\n### Named imports\n\nFor ESM / TypeScript projects:\nBetter for tree-shaking.\n\n```ts\nimport { sll, pow, sqrt, lerp, sin, cos, seq, select } from \"@stationeers-ic/exact-ic10-math\"\n\nconsole.log(sll(1, 2)) // 4\nconsole.log(pow(2, 3)) // 8\nconsole.log(sqrt(9)) // 3\nconsole.log(lerp(0, 10, 0.5)) // 5\nconsole.log(sin(Math.PI / 2)) // 1\nconsole.log(cos(0)) // 1\nconsole.log(seq(1, 1)) // 1\nconsole.log(select(1, 42, 0)) // 42\n```\n\n## API Reference\n\n### String Hashing (CRC32)\n\nThe library includes `hashString(str)` — a CRC32 implementation that computes a numeric hash for any string, matching the game's hashing behavior. Useful for converting device names or other string identifiers into numeric values.\n\n```ts\nimport { hashString } from \"@stationeers-ic/exact-ic10-math\"\n\nconsole.log(hashString(\"StructureAirlockGate\")) // 1736080881\n```\n\n### ASCII Packing\n\nHelper functions for packing and unpacking short ASCII strings into numbers.\n\n```ts\nimport { PackAscii6, UnpackAscii6 } from \"@stationeers-ic/exact-ic10-math\"\n\nconsole.log(PackAscii6(\"abc\")) // 6382179\nconsole.log(UnpackAscii6(6382179)) // \"abc\"\n```\n\n**Notes:**\n\n-   `PackAscii6` packs up to 6 ASCII characters (8 bits per character) into a single number and returns that numeric value. It returns `null` for invalid inputs.\n-   `UnpackAscii6` reverses the operation and returns the original string. It accepts an optional `signed` boolean (default `true`) for completeness; in the game the `signed` flag is always `true`.\n\n### Random Number Generation\n\nA deterministic PRNG that mirrors the game's behavior.\n\n**Key API:**\n\n-   `new Random(seed?)` — create a generator; if omitted a seed is generated for you and available as `instance.seed`.\n-   `rand(random?)` — convenience wrapper. Pass a `Random` instance to use its `nextDouble()`; calling `rand()` with no argument uses the internal global RNG. Prefer passing your own instance for independent or reproducible streams.\n-   `Random.resetGlobalRandom(seed?)` — reseed (provide a `seed`) or clear (no args) the internal global RNG.\n-   `Random.getGlobalRandomSeed()` — read the currently-set global seed (or `null` if none).\n\n**Why this matters:**\n\nCreate a separate `Random` instance for each in-game code line (or logical RNG stream) to reproduce the game's behavior and avoid accidental sequence coupling.\n\n**Example:**\n\n```ts\nimport { Random, rand } from \"@stationeers-ic/exact-ic10-math\"\n\nconst rngLineA = new Random()\nconst rngLineB = new Random()\n\nconsole.log(rand(rngLineA))\nconsole.log(rand(rngLineB))\n\nconsole.log(rngLineA.seed)\nconsole.log(rngLineB.seed)\n\n// Deterministic runs: pass a seed\n// const rngDet = new Random(12345)\n```\n\n**Notes:**\n\n-   Tests validate specific integer sequences and floating outputs to ensure reproducible values across platforms.\n-   For fully reproducible runs, keep and use your own `Random` instances rather than relying on the global RNG.\n\n#### Replaying Runs / Capturing Seeds\n\nTwo approaches for reproducible random sequences:\n\n**1. Global seed approach** — Replay entire run by seeding the global generator:\n\n```ts\nimport { Random } from \"@stationeers-ic/exact-ic10-math\"\n\n// choose and record this seed for replay\nRandom.resetGlobalRandom(111098293)\n\nconst a = new Random()\nconst b = new Random()\n\nconsole.log(Random.getGlobalRandomSeed() /* -\u003e 111098293 */)\nconsole.log(a.seed, b.seed)\n\n// Later, to replay the same run:\nRandom.resetGlobalRandom(111098293)\nconst a2 = new Random()\nconst b2 = new Random()\n// a2.seed === a.seed, b2.seed === b.seed\n// rand(a) === rand(a2)\n// rand(b) === rand(b2)\n```\n\n**2. Instance seed approach** — Capture and replay individual generator:\n\n```ts\nconst r = new Random()\nconsole.log(r.seed) // store this value\n\n// later\nconst rReplay = new Random(r.seed)\n```\n\n**Use the global-seed approach** when you want to reproduce the full set of generated instance seeds; **use the instance-seed approach** when you only need to replay a single generator.\n\n## Compatibility Note\n\nThis library reproduces Stationeers' IC10 instruction semantics exactly — use it when you need faithful in-game behavior; other JS/TS libraries may differ in edge cases.  \nBased on Stationeers v0.2.5954.26176 (16.10.2025)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstationeers-ic%2Fexact-ic10-math","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstationeers-ic%2Fexact-ic10-math","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstationeers-ic%2Fexact-ic10-math/lists"}