{"id":36503383,"url":"https://github.com/soonfx-engine/core","last_synced_at":"2026-03-04T09:31:23.036Z","repository":{"id":323425729,"uuid":"1091606325","full_name":"soonfx-engine/core","owner":"soonfx-engine","description":"🎮 TypeScript game numeric engine for RPG \u0026 strategy games. Zero dependencies, type-safe formula parsing, battle system simulation, and expression evaluation.  基于 TypeScript 的游戏数值引擎，专为 RPG 和策略游戏设计。零依赖、类型安全的公式解析、战斗系统模拟和表达式计算。","archived":false,"fork":false,"pushed_at":"2025-12-30T02:15:53.000Z","size":8285,"stargazers_count":747,"open_issues_count":8,"forks_count":101,"subscribers_count":46,"default_branch":"main","last_synced_at":"2026-01-12T04:57:02.425Z","etag":null,"topics":["battle-system","card-game","character-attributes","damage-calculation","expression-parser","formula-engine","game-development","game-engine","game-formula","game-logic","game-math","javascript","numeric-calculation","rpg","simulation","strategy-game","turn-based","typescript","visual-programming","zero-dependencies"],"latest_commit_sha":null,"homepage":"https://soonfx.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soonfx-engine.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-07T08:54:27.000Z","updated_at":"2026-01-11T10:50:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/soonfx-engine/core","commit_stats":null,"previous_names":["jiyi-soon-fx/soonfx","soonfx-engine/core"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/soonfx-engine/core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soonfx-engine%2Fcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soonfx-engine%2Fcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soonfx-engine%2Fcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soonfx-engine%2Fcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soonfx-engine","download_url":"https://codeload.github.com/soonfx-engine/core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soonfx-engine%2Fcore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30077069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T08:01:56.766Z","status":"ssl_error","status_checked_at":"2026-03-04T08:00:42.919Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["battle-system","card-game","character-attributes","damage-calculation","expression-parser","formula-engine","game-development","game-engine","game-formula","game-logic","game-math","javascript","numeric-calculation","rpg","simulation","strategy-game","turn-based","typescript","visual-programming","zero-dependencies"],"created_at":"2026-01-12T02:26:35.703Z","updated_at":"2026-03-04T09:31:22.996Z","avatar_url":"https://github.com/soonfx-engine.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n\n# SoonFx Runtime\n \n\n\u003e **The TypeScript-first numeric engine for games.**  \n\u003e Decouple logic from code, manage complex formulas with ease, and build robust RPG/SLG/Card systems.\n\n[![npm version](https://img.shields.io/npm/v/@soonfx/engine.svg)](https://www.npmjs.com/package/@soonfx/engine)\n[![npm downloads](https://img.shields.io/npm/dm/@soonfx/engine.svg)](https://www.npmjs.com/package/@soonfx/engine)\n[![CI](https://github.com/soonfx-engine/core/actions/workflows/ci.yml/badge.svg)](https://github.com/soonfx-engine/core/actions/workflows/ci.yml)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n\n[Installation](#-installation) · [Quick Start](#-quick-start) · [Documentation](#-core-api) · [Examples](examples) · [Roadmap](ROADMAP.md) · [Online Demo](https://soonfx.dev)\n\n[English](README.md) | [简体中文](README.zh-CN.md)\n\n\u003c/div\u003e\n\n---\n\n## ❓ What is SoonFx?\n\n\u003cimg src=\"assets/editor.gif\" align=\"right\" width=\"250\" style=\"margin-left: 6px;\" alt=\"SoonFx Editor Preview\"\u003e\n\nSoonFx is a **TypeScript-first numeric engine** designed specifically for games. It addresses the common challenge of managing complex game logic, formulas, and numeric relationships that often become hardcoded \"spaghetti code.\"\n\n### 🚫 The Problem\n\nIn many game projects, damage calculations, resource production rates, and other numeric logic are hardcoded directly into the source code.\n\n*   **Hard to maintain**: Formulas are buried in nested if-else statements.\n*   **Slow iteration**: Designers need engineers to change a simple constant or formula structure.\n*   **Bug prone**: Copy-pasting logic leads to subtle errors.\n\n### ✅ The Solution\n\nSoonFx decouples **logic** from **code**.\n\n1.  **Logic as Data**: Formulas and relationships are defined as data (JSON).\n2.  **Runtime Execution**: The engine parses and executes this data safely at runtime.\n3.  **Visual Tooling**: Designers use the [SoonFx Editor](https://github.com/soonfx-engine/editor) to visually build these relationships.\n\n---\n\n## 🎨 Visual Editor Driven\n\nStop hardcoding formulas. Build them visually.\n\n**SoonFx Runtime** is the engine that powers the **[SoonFx Editor](https://github.com/soonfx-engine/editor)**. It allows game designers to configure complex logic without writing a single line of code, while developers can safely execute it at runtime.\n\n### The Workflow\n\n1.  **Design**: Designers create formulas, skill effects, and attribute relationships in the **Visual Editor**.\n2.  **Export**: The editor generates a JSON configuration file.\n3.  **Run**: The **SoonFx Runtime** loads this JSON and executes the logic in your game.\n\n\u003e **Note**: While SoonFx Runtime can be used standalone for math and expressions, its true power is unlocked when paired with the Editor.\n\n![SoonFx Editor](assets/editor.gif)\n\n## 💡 Use Cases\n\nSoonFx is designed for numeric-heavy game genres:\n\n*   ⚔️ **RPG Systems**: Skill damage, character stats growth, equipment bonuses, combat power (CP) calculations.\n*   🏰 **SLG / Strategy**: Resource production rates, building upgrade timers, marching times, tech tree requirements.\n*   🃏 **Card Games**: Dynamic card values, synergy effects, deck balancing simulation.\n*   📊 **Simulation**: Complex economy models, probability calculations.\n\n---\n\n## 📸 Demo\n\n### [Runtime Demo](https://soonfx.dev/)\n\n![Demo](assets/demo1.gif) \n![Demo](assets/demo2.gif)\n\n## ✨ Features\n\n- ⚡ **Zero Dependencies** - Lightweight and fast, less than 50KB minified\n- 🛡️ **Type-Safe** - Full TypeScript support with strict typing and intelligent code completion\n- 📐 **Expression Engine** - Parse and evaluate complex mathematical expressions with RPN conversion\n- 🎮 **Battle System** - Built-in RPG battle simulation with character attributes and damage calculation\n- 🔧 **Extensible** - Flexible operator system supporting complex game logic and formula combinations\n- 📦 **Tree-shakable** - Modern ESM support with CommonJS fallback\n\n## 🚀 For Users\n\nTo use this library in your project:\n\n```bash\nnpm install @soonfx/engine\n```\n\n## 📦 Development Setup\n\nClone and setup the development environment:\n\n```bash\n# Clone the repository\ngit clone https://github.com/soonfx-engine/core.git\ncd core\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run examples\ncd examples\nnpm install\nnpm run dev\n```\n\n## 🎯 Quick Start\n\n### Basic Usage\n\n```typescript\nimport { fx } from '@soonfx/engine';\n\n// 1. Mathematical utilities\nconst distance = fx.distance(0, 0, 10, 10);\nconsole.log('Distance between points:', distance); // 14.142135623730951\n\n// 2. Expression evaluation\nconst result = fx.evaluateExpression('(2 + 3) * 4');\nconsole.log('Expression result:', result); // 20\n\n// 3. Numeric processing\nconst fixed = fx.fixedDecimal(3.14159, 2);\nconsole.log('Fixed to 2 decimals:', fixed); // 3.14\n```\n\n### Event System\n\n```typescript\nimport { Eve, Call, CallCenter } from '@soonfx/engine';\n\n// Create event call center\nconst callCenter = new CallCenter();\n\n// Listen to events\ncallCenter.addEventListener(Eve.SHIFT_ADD_BOARD, (data) =\u003e {\n    console.log('Board added event triggered:', data);\n});\n\n// Send events\nCall.send(Eve.ADD_DATABASE_DATA, [data, body, index]);\n```\n\n## 📚 Core API\n\n### Mathematical Utilities (fx)\n\n#### Vector and Geometry Operations\n```typescript\n// Calculate distance between two points\nconst distance = fx.distance(x1, y1, x2, y2);\n\n// Vector dot product\nconst dotProduct = fx.dot(p1x, p1y, p2x, p2y);\n\n// Vector cross product\nconst crossProduct = fx.cross(p1x, p1y, p2x, p2y);\n\n// Calculate vector length\nconst length = fx.length(a, b);\n\n// Coordinate transformation\nconst coord = fx.coordinate(x, y, angle, distance);\n```\n\n### Game Characters (Player)\n\nThe `Player` class provides character attributes, battle calculations, and combat simulation. See the [Examples](#-examples) section below for complete battle system demonstrations.\n\n## 🏗️ System Architecture\n\n```\n@soonfx/fx\n├── Core Systems (core/)\n│   ├── EventManager      Event management\n│   ├── System            System base class\n│   └── Types             Type definitions\n│\n├── Mathematical Modules\n│   ├── Vector            Vector operations (dot, cross, distance)\n│   ├── Numeric           Numeric processing (fixedDecimal, currencyConversion)\n│   └── Geometry          Geometric calculations (coordinate, length)\n│\n├── Expression System\n│   ├── Parser            Expression parser\n│   ├── RPN Converter     Reverse Polish Notation converter\n│   └── Evaluator         Evaluation engine\n│\n├── Data Management (data/)\n│   ├── Layers            Layer system\n│   ├── Metadata          Metadata management\n│   ├── Models            Data models\n│   └── Storage           Storage system\n│\n├── Game Systems (game/)\n│   ├── FXCentre          Game engine core\n│   ├── Player            Player character system\n│   └── Formulas          Formula calculation system\n│\n├── Communication (communication/)\n│   ├── Events            Event system\n│   ├── Call              Event calling\n│   └── Message           Message passing\n│\n└── Utilities (utils/)\n    └── ExtendsUtil       Extension utilities\n```\n\n## 📖 Examples\n\nCheck out the [example project](https://github.com/soonfx-engine/core/tree/main/examples) for complete development examples.\n\n### Example Contents:\n\n- ⚔️ Battle system simulation\n- 📊 Character attribute calculations\n- 🎯 PVE data generation\n- 📈 Multi-battle comparison analysis\n- 🎮 Complete game numeric system demonstration\n\n### Run Examples Locally:\n\nSee the [Getting Started](#getting-started) section in Contributing for setup instructions.\n\n## 🛠️ TypeScript Support\n\nSoonFx provides complete TypeScript type definitions:\n\n```typescript\n// Automatic type inference\nconst distance: number = fx.distance(0, 0, 10, 10);\n\n// Full IntelliSense support\nfx. // IDE will show all available methods\n```\n\n### Type Definition Features:\n\n- ✅ Complete TypeScript type definitions (.d.ts)\n- ✅ Intelligent code completion\n- ✅ Type checking and error hints\n- ✅ Parameter type inference\n- ✅ Return type inference\n\n## 🔧 Browser and Environment Support\n\n### Supported Environments\n\n- ✅ **Node.js** \u003e= 14.0.0\n- ✅ **Modern Browsers** (ES2015+)\n  - Chrome, Firefox, Safari, Edge (latest versions)\n- ✅ **Build Tools**\n  - esbuild (recommended, used in this project)\n  - Webpack, Vite, Rollup, and other modern bundlers\n\n### Module Systems\n\n- ✅ **ESM** (ES Modules) - Recommended\n- ✅ **CommonJS** - Node.js environment\n\n## 🤝 Contributing\n\nWe welcome all forms of contributions!\n\n### Getting Started\n\nFirst, clone the repository:\n\n```bash\ngit clone https://github.com/soonfx-engine/core.git\ncd core\n```\n\n#### To Run Examples:\n\n```bash\n# Navigate to examples directory\ncd examples\n\n# Install dependencies\nnpm install\n\n# Start development server\nnpm run dev\n\n# Build for production\nnpm run build\n```\n\n#### To Contribute Code:\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run tests (if available)\nnpm test\n```\n\n## 🗺️ Roadmap\n\nSee our [Roadmap](ROADMAP.md) for planned features and improvements.\n\n## 📝 Changelog\n\nView the [complete changelog](https://github.com/soonfx-engine/core/releases)\n\n## 📄 License\n\nThis project is licensed under the [Apache 2.0 License](LICENSE). You are free to use, modify, and distribute this project.\n\n## 🔗 Links\n\n- 📦 [npm Package](https://www.npmjs.com/package/@soonfx/engine)\n- 💻 [GitHub Repository](https://github.com/soonfx-engine/core)\n- 📖 [Online Demo](https://soonfx.dev)\n- 🐛 [Issue Tracker](https://github.com/soonfx-engine/core/issues)\n- 💬 [Discussions](https://github.com/soonfx-engine/core/discussions)\n\n## 📞 Getting Help\n\nIf you encounter any issues:\n\n- 💬 [GitHub Discussions](https://github.com/soonfx-engine/core/discussions) - Ask questions and discuss\n- 🐛 [GitHub Issues](https://github.com/soonfx-engine/core/issues) - Bug reports and feature requests\n- 📧 [jiyisoon@163.com](mailto:jiyisoon@163.com) - Email contact\n\n## ⭐ Star History\n\nIf this project helps you, please give us a Star! It means a lot to us.\n\n[![Star History Chart](https://api.star-history.com/svg?repos=soonfx-engine/core\u0026type=Date)](https://star-history.com/#soonfx-engine/core\u0026Date)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[⬆ Back to Top](#soonfx)**\n\nMade with ❤️ by [SoonFx Team](https://github.com/soonfx-engine)\n\nCopyright © 2025 SoonFx Team. All rights reserved.\n\n\u003c/div\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoonfx-engine%2Fcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoonfx-engine%2Fcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoonfx-engine%2Fcore/lists"}