SoonFx Runtime

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

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.

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.

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.

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.

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.

• ⚡ 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

To use this library in your project:

npm install @soonfx/engine

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

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

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]);

// 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);

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

@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

Check out the example project for complete development examples.

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

See the Getting Started section in Contributing for setup instructions.

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

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

• ✅ 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

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

We welcome all forms of contributions!

First, clone the repository:

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

# Navigate to examples directory
cd examples

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Install dependencies
npm install

# Build the project
npm run build

# Run tests (if available)
npm test

See our Roadmap for planned features and improvements.

View the complete changelog

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

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

If you encounter any issues:

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

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