SoonFx Runtime

The TypeScript-first numeric engine for games.
Decouple logic from code, manage complex formulas with ease, and build robust RPG/SLG/Card systems.

Installation · Quick Start · Documentation · Examples · Roadmap · Online Demo

English | 简体中文

---

❓ What is SoonFx?

SoonFx 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."

🚫 The Problem

In many game projects, damage calculations, resource production rates, and other numeric logic are hardcoded directly into the source code.

• Hard to maintain: Formulas are buried in nested if-else statements.
• Slow iteration: Designers need engineers to change a simple constant or formula structure.
• Bug prone: Copy-pasting logic leads to subtle errors.

✅ The Solution

SoonFx decouples logic from code.

1. Logic as Data: Formulas and relationships are defined as data (JSON).
2. Runtime Execution: The engine parses and executes this data safely at runtime.
3. Visual Tooling: Designers use the SoonFx Editor to visually build these relationships.

---

🎨 Visual Editor Driven

Stop hardcoding formulas. Build them visually.

SoonFx Runtime is the engine that powers the SoonFx Editor. It allows game designers to configure complex logic without writing a single line of code, while developers can safely execute it at runtime.

The Workflow

1. Design: Designers create formulas, skill effects, and attribute relationships in the Visual Editor.
2. Export: The editor generates a JSON configuration file.
3. Run: The SoonFx Runtime loads this JSON and executes the logic in your game.

Note: While SoonFx Runtime can be used standalone for math and expressions, its true power is unlocked when paired with the Editor.

💡 Use Cases

SoonFx is designed for numeric-heavy game genres:

• ⚔️ RPG Systems: Skill damage, character stats growth, equipment bonuses, combat power (CP) calculations.
• 🏰 SLG / Strategy: Resource production rates, building upgrade timers, marching times, tech tree requirements.
• 🃏 Card Games: Dynamic card values, synergy effects, deck balancing simulation.
• 📊 Simulation: Complex economy models, probability calculations.

---

📸 Demo

Runtime Demo

✨ Features

• ⚡ Zero Dependencies - Lightweight and fast, less than 50KB minified
• 🛡️ Type-Safe - Full TypeScript support with strict typing and intelligent code completion
• 📐 Expression Engine - Parse and evaluate complex mathematical expressions with RPN conversion
• 🎮 Battle System - Built-in RPG battle simulation with character attributes and damage calculation
• 🔧 Extensible - Flexible operator system supporting complex game logic and formula combinations
• 📦 Tree-shakable - Modern ESM support with CommonJS fallback

🚀 For Users

To use this library in your project:

npm install @soonfx/engine

📦 Development Setup

Clone and setup the development environment:

# Clone the repository
git clone https://github.com/soonfx-engine/core.git
cd core

# Install dependencies
npm install

# Build the project
npm run build

# Run examples
cd examples
npm install
npm run dev

🎯 Quick Start

Basic Usage

import { fx } from '@soonfx/engine';

// 1. Mathematical utilities
const distance = fx.distance(0, 0, 10, 10);
console.log('Distance between points:', distance); // 14.142135623730951

// 2. Expression evaluation
const result = fx.evaluateExpression('(2 + 3) * 4');
console.log('Expression result:', result); // 20

// 3. Numeric processing
const fixed = fx.fixedDecimal(3.14159, 2);
console.log('Fixed to 2 decimals:', fixed); // 3.14

Event System

import { Eve, Call, CallCenter } from '@soonfx/engine';

// Create event call center
const callCenter = new CallCenter();

// Listen to events
callCenter.addEventListener(Eve.SHIFT_ADD_BOARD, (data) => {
    console.log('Board added event triggered:', data);
});

// Send events
Call.send(Eve.ADD_DATABASE_DATA, [data, body, index]);

📚 Core API

Mathematical Utilities (fx)

Vector and Geometry Operations

// Calculate distance between two points
const distance = fx.distance(x1, y1, x2, y2);

// Vector dot product
const dotProduct = fx.dot(p1x, p1y, p2x, p2y);

// Vector cross product
const crossProduct = fx.cross(p1x, p1y, p2x, p2y);

// Calculate vector length
const length = fx.length(a, b);

// Coordinate transformation
const coord = fx.coordinate(x, y, angle, distance);

Game Characters (Player)

The Player class provides character attributes, battle calculations, and combat simulation. See the Examples section below for complete battle system demonstrations.

🏗️ System Architecture

@soonfx/fx
├── Core Systems (core/)
│   ├── EventManager      Event management
│   ├── System            System base class
│   └── Types             Type definitions
│
├── Mathematical Modules
│   ├── Vector            Vector operations (dot, cross, distance)
│   ├── Numeric           Numeric processing (fixedDecimal, currencyConversion)
│   └── Geometry          Geometric calculations (coordinate, length)
│
├── Expression System
│   ├── Parser            Expression parser
│   ├── RPN Converter     Reverse Polish Notation converter
│   └── Evaluator         Evaluation engine
│
├── Data Management (data/)
│   ├── Layers            Layer system
│   ├── Metadata          Metadata management
│   ├── Models            Data models
│   └── Storage           Storage system
│
├── Game Systems (game/)
│   ├── FXCentre          Game engine core
│   ├── Player            Player character system
│   └── Formulas          Formula calculation system
│
├── Communication (communication/)
│   ├── Events            Event system
│   ├── Call              Event calling
│   └── Message           Message passing
│
└── Utilities (utils/)
    └── ExtendsUtil       Extension utilities

📖 Examples

Check out the example project for complete development examples.

Example Contents:

• ⚔️ Battle system simulation
• 📊 Character attribute calculations
• 🎯 PVE data generation
• 📈 Multi-battle comparison analysis
• 🎮 Complete game numeric system demonstration

Run Examples Locally:

See the Getting Started section in Contributing for setup instructions.

🛠️ TypeScript Support

SoonFx provides complete TypeScript type definitions:

// Automatic type inference
const distance: number = fx.distance(0, 0, 10, 10);

// Full IntelliSense support
fx. // IDE will show all available methods

Type Definition Features:

• ✅ Complete TypeScript type definitions (.d.ts)
• ✅ Intelligent code completion
• ✅ Type checking and error hints
• ✅ Parameter type inference
• ✅ Return type inference

🔧 Browser and Environment Support

Supported Environments

• ✅ Node.js >= 14.0.0
• ✅ Modern Browsers (ES2015+)
  • Chrome, Firefox, Safari, Edge (latest versions)
• ✅ Build Tools
  • esbuild (recommended, used in this project)
  • Webpack, Vite, Rollup, and other modern bundlers

Module Systems

• ✅ ESM (ES Modules) - Recommended
• ✅ CommonJS - Node.js environment

🤝 Contributing

We welcome all forms of contributions!

Getting Started

First, clone the repository:

git clone https://github.com/soonfx-engine/core.git
cd core

To Run Examples:

# Navigate to examples directory
cd examples

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

To Contribute Code:

# Install dependencies
npm install

# Build the project
npm run build

# Run tests (if available)
npm test

🗺️ Roadmap

See our Roadmap for planned features and improvements.

📝 Changelog

View the complete changelog

📄 License

This project is licensed under the Apache 2.0 License. You are free to use, modify, and distribute this project.

🔗 Links

• 📦 npm Package
• 💻 GitHub Repository
• 📖 Online Demo
• 🐛 Issue Tracker
• 💬 Discussions

📞 Getting Help

If you encounter any issues:

• 💬 GitHub Discussions - Ask questions and discuss
• 🐛 GitHub Issues - Bug reports and feature requests
• 📧 jiyisoon@163.com - Email contact

⭐ Star History

If this project helps you, please give us a Star! It means a lot to us.

---

⬆ Back to Top

Made with ❤️ by SoonFx Team

Copyright © 2025 SoonFx Team. All rights reserved.