SoonFx

TypeScript-first game numeric engine for RPG and strategy games

A lightweight, type-safe formula engine designed for game developers who need reliable battle calculations, character attributes, and expression parsing - with zero dependencies.

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

English | 简体中文

---

📸 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

💡 Use Cases

Ideal for These Game Types:

• 🎲 Turn-based Games - Complex numeric calculations and battle systems
• ⚔️ Role-Playing Games (RPG) - Character attributes, skills, and equipment systems
• 🏆 Strategy Games - Numerical balance and formula systems
• 🎮 Card Games - Card attribute calculation and effect systems
• 📊 Simulation Games - Complex numerical simulation and calculations

Main Applications:

• ✅ Character attribute calculations (attack, defense, HP, etc.)
• ✅ Battle damage calculation and combat simulation
• ✅ Equipment and item effect calculations
• ✅ Skill and buff systems
• ✅ Level and experience systems
• ✅ Game balance testing

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