Skip to content

MystiC1988/imps_adventure_simulator

Repository files navigation

🎲 Imp's Simulator - 2025

A powerful probability simulator for strategic board event planning in idle RPG games. This fan-made tool helps players optimize their gameplay decisions through Monte Carlo simulations.

Flutter Dart License Platform


⚖️ 🚨 IMPORTANT LEGAL DISCLAIMERS 🚨

This is a FAN-MADE TOOL - NOT AFFILIATED WITH ANY VIDEO GAME COMPANY

⚠️ CRITICAL NOTICE - PLEASE READ:

This application is an independent fan-made project created by hobby enthusiasts. It is NOT:

  • ❌ Endorsed, sponsored, or authorized by any video game publisher
  • ❌ Part of, affiliated with, or derived from any original game
  • ❌ A commercial product competing with any game publisher's offerings
  • ❌ Intended to infringe on any intellectual property rights
  • ❌ Connected to any official game company in any way

This tool is provided AS-IS for:

  • Educational purposes only
  • Entertainment and non-commercial use only
  • Probability estimation and strategic planning
  • Personal learning about simulation algorithms

Intellectual Property Notice

  • All game mechanics, dynamics, and scenarios are generalized and modified to avoid infringement
  • This is a simulation utility tool, NOT a game replica
  • The application includes proper disclaimers throughout its interface
  • All assets are either original creations or licensed under permissive licenses (Freepik)
  • No official game content, code, or proprietary information is used

Liability Disclaimer - READ CAREFULLY

USE AT YOUR OWN RISK. While every effort has been made to ensure correctness:

  • NO WARRANTY IS PROVIDED - express or implied
  • Developer is NOT LIABLE for any damage, loss, or inconvenience from using this application
  • Simulation results are estimates only and may not reflect actual game outcomes
  • Always verify calculations independently before making important decisions
  • Results should not be relied upon for competitive or commercial purposes

Content Attribution

  • Graphics: Original creations + Freepik free-use license
  • AI-generated content used with appropriate license permissions
  • Custom fonts and assets properly licensed
  • All third-party content properly credited

📱 What is Imp's Simulator?

Imp's Simulator is a sophisticated Monte Carlo probability calculator designed to help players make informed strategic decisions in board-based idle RPG events. Instead of guessing outcomes, users can run thousands of simulations to understand the probability distribution of their results.

What It Does ✅

This tool simulates and calculates probabilities for:

  • Dice roll mechanics - Probability distributions based on normal and special dice
  • Position-based events - Movement and interactions across a 20-tile board
  • Resource generation - Reward distributions from different tile types
  • Card effects - Special card mechanics and their probabilities
  • Strategy comparison - Tests different tactical approaches simultaneously
  • Large-scale analysis - Runs up to 1,000,000 simulations for statistical accuracy

What It Does NOT Do ❌

  • ❌ Connect to any game server
  • ❌ Access or modify game accounts
  • ❌ Provide guaranteed outcomes
  • ❌ Replace official game guides
  • ❌ Generate in-game resources or rewards
  • ❌ Violate any game terms of service (it's just a calculator)

✨ Key Features

Core Functionality

  • 🎲 Advanced Probability Simulator - Monte Carlo-based calculation engine
  • 📊 Statistical Analysis - Min, max, average, and percentile distributions
  • 🎯 Strategy Comparison - Test multiple strategies in parallel
  • ⚙️ Customizable Parameters - Adjust all input variables
  • 🌍 Multi-language Support - English and Spanish interfaces

User Experience

  • 🎨 Beautiful Custom UI - Pixel-perfect interface design
  • Fast Calculations - Highly optimized Dart implementation
  • 📱 Mobile-Optimized - Responsive design for all screen sizes
  • 🌙 Theme Adaptive - Light and dark mode support
  • Accessible - Clear typography and high contrast

Technical Excellence

  • 🔄 Reactive State - GetX for responsive programming patterns
  • 📈 Live Progress - Real-time simulation progress tracking
  • 💾 Persistent Settings - Save and restore user preferences
  • 🎬 Smooth Animations - Professional visual polish
  • 🔐 Offline-First - Fully functional without internet connection

🛠️ Development Stack

Frontend & Framework

  • Flutter 3.0+ - Cross-platform mobile development
  • Dart 2.19+ - Modern, null-safe programming language
  • Material Design 3 - Modern design system

State Management & Routing

  • GetX 4.6+ - Reactive state management, dependency injection, routing
  • get_storage - Local persistent storage for settings

UI & Animation

  • Animate_do - Smooth entrance and exit animations
  • Custom Widgets - Purpose-built UI components for the application
  • Material Components - Flutter's extensive UI widget library

Simulation Engine

  • Pure Dart Implementation - No external simulation libraries
  • Monte Carlo Algorithm - Statistical probability calculation
  • Isolates - Optimized multi-threading for large simulations

Additional Technologies

  • flutter_dotenv - Environment configuration management
  • purchases_flutter - RevenueCat integration (optional premium features)
  • intl - Internationalization and localization support

Build & Development Tools

  • Gradle - Android build system
  • CocoaPods - iOS dependency management
  • Android Studio - Android development environment
  • Xcode - iOS development and compilation
  • Flutter CLI - Cross-platform development tooling

📁 Project Architecture

imps_adventure_simulator/
├── lib/
│   ├── main.dart                    # Application entry point & configuration
│   ├── getx_routes.dart             # Navigation routes definition
│   ├── models/                      # Core data models & logic
│   │   ├── simulator/               # Game simulation engine
│   │   │   ├── board.dart           # Board state and mechanics
│   │   │   ├── player.dart          # Player state and interactions
│   │   │   └── simulation_stats.dart # Statistics aggregation
│   │   ├── enums/                   # Game enumerations
│   │   ├── positions/               # Special board position types
│   │   └── expressions/             # Conditional logic system
│   ├── presentation/
│   │   ├── screens/                 # Full-screen page views
│   │   ├── widgets/
│   │   │   ├── blocks/              # Reusable UI sections
│   │   │   ├── containers/          # Container components
│   │   │   ├── buttons/             # Custom button implementations
│   │   │   ├── headers/             # Header and title components
│   │   │   └── textfields/          # Input field components
│   │   ├── controllers/             # GetX reactive controllers
│   │   └── utils/                   # UI utility functions
│   ├── translations/                # Multi-language string resources
│   │   ├── en_US.dart              # English translations
│   │   └── es_ES.dart              # Spanish translations
│   └── revenuecat/                  # Optional monetization integration
├── assets/
│   ├── fonts/                       # Custom typography
│   └── images/                      # UI graphics and icons
│       ├── cards/                   # Card game asset graphics
│       ├── resources/               # Resource reward icons
│       └── stars/                   # Star and reward graphics
├── android/                         # Android-specific native code
├── ios/                             # iOS-specific native code
├── pubspec.yaml                     # Project dependencies
└── analysis_options.yaml            # Lint and analysis rules

🚀 Getting Started

Prerequisites

  • Flutter SDK 3.0 or higher (Download)
  • Dart SDK 2.19 or higher (included with Flutter)
  • Android Studio or Xcode (for native development)
  • Git for version control

Installation Steps

  1. Clone the repository
git clone https://github.com/yourusername/imps-simulator.git
cd imps_adventure_simulator
  1. Install Flutter dependencies
flutter pub get
  1. Set up environment configuration
cp .env.example .env
# Edit .env with your configuration (optional)
  1. Run the application
# Development mode
flutter run

# Release APK (Android)
flutter build apk --release

# Release app bundle (Android)
flutter build appbundle

# Release build (iOS)
flutter build ios --release

Initial Setup

# Get all dependencies
flutter pub get

# Run code generation (if using build_runner)
flutter pub run build_runner build

# Analyze code quality
flutter analyze

# Run tests
flutter test

📖 How to Use the Application

Step-by-Step Guide

1. Configure Your Parameters

  • Number of normal dice to spend
  • Current board position (0-20)
  • Current constellation count (stars earned)
  • Special position levels (tiles 4, 11, 18)

2. Select Active Strategies

  • Choose which game strategies to apply
  • Enable/disable optimization modes
  • Select active card effects if applicable

3. Adjust Simulation Settings

  • Set number of simulations (1,000 to 1,000,000)
  • Review strategy descriptions
  • Enable/disable individual strategies

4. Run the Simulation

  • Click "Start Simulation" button
  • Watch real-time progress indicator
  • Wait for completion (varies by simulation count)

5. Analyze Results

  • View minimum, maximum, and average outcomes
  • Check probability percentages (80%, 110%, 140%, etc.)
  • Estimate resource rewards by tier
  • Review obtained card distributions

Available Strategies

Active Strategies (enabled by default):

  • Fortune Dice Optimization - Regenerate single fortune die for next round
  • No Luck in Position 19 - Avoid wasting fortune dice at specific tiles
  • Optimize Fortune Card - Maximize special card effect usage

Passive Strategies (automatic):

  • Save for Rewards - Preserve dice for reward milestones
  • Maximize Remaining - Optimize dice usage when count is low

🔬 Simulation Algorithm & Methodology

Monte Carlo Approach

The simulator uses a proven Monte Carlo method:

  1. State Initialization - Set up initial game state with user parameters
  2. Iteration Loop - Simulate each individual action/roll
  3. Event Processing - Apply board mechanics and strategy logic
  4. Outcome Tracking - Record results at each step
  5. Result Aggregation - Compile statistics across all runs
  6. Analysis Generation - Calculate percentiles and distributions

Performance Characteristics

Simulations Time (Mid-Range Phone) Time (High-End Phone)
1,000 ~50ms ~20ms
10,000 ~250ms ~100ms
100,000 ~2.5s ~1s
500,000 ~12s ~5s
1,000,000 ~25s ~10s

Note: Times vary based on device specifications and background processes.

Accuracy & Reliability

  • Results are probabilistic estimates, not guarantees
  • Accuracy improves with more simulations (diminishing returns after 100K)
  • Statistical confidence improves significantly above 50,000 simulations
  • Results should be used for decision support, not guaranteed predictions

🌐 Language Support

Currently available:

  • 🇺🇸 English (US) - Full implementation
  • 🇪🇸 Spanish (España) - Complete translation

Adding New Languages

// 1. Create translation file: lib/translations/[locale].dart
final Map<String, String> [locale] = { ... };

// 2. Register in lib/translations/translations.dart
'[locale_code]': [locale],

// 3. Translations auto-loaded based on device locale

📊 System Requirements

Minimum Requirements

  • Android 8.0 (API 26) or higher
  • iOS 12.0 or higher
  • RAM: 2GB minimum
  • Storage: ~50MB installation

Recommended

  • Android 10 or higher
  • iOS 14 or higher
  • RAM: 4GB or more
  • Processor: Snapdragon 845+ or Apple A10 equivalent
  • Storage: 100MB+ available

Device Support

  • ✅ Android phones and tablets
  • ✅ iPhones (6S and newer)
  • ✅ iPad (5th generation and newer)
  • ✅ Landscape and portrait orientation (portrait optimized)

🐛 Known Limitations & Issues

Current Limitations

  • Maximum 1,000,000 simulations per run (device memory)
  • Portrait orientation only (landscape in development)
  • Simulations run locally only (no cloud processing)
  • iOS requires macOS and Xcode for building

Known Issues

  • Devices with <2GB RAM may experience slowdowns with 1M simulations
  • Very old Android devices (pre-4.4) not supported
  • Some emoji may render differently on older devices

Workarounds

  • Reduce simulation count on lower-end devices
  • Close background applications before running large simulations
  • Restart device if performance degrades

🛣️ Development Roadmap

✅ Completed

  • Core simulation engine implementation
  • Multi-language interface (EN, ES)
  • Strategy selection and comparison
  • Mobile optimization and UI polish
  • Offline functionality
  • Settings persistence

🔄 In Progress

  • Cloud synchronization
  • Historical result tracking
  • Advanced statistical reports
  • Community features

📋 Planned for Future

  • Desktop versions (Windows/Mac/Linux)
  • Web application
  • Real-time community sharing
  • AI-powered strategy recommendations
  • Dark theme optimization

🤝 Contributing Guide

We welcome contributions from the community! Here's how:

Development Workflow

# 1. Fork and clone
git clone https://github.com/yourusername/imps-simulator.git

# 2. Create feature branch
git checkout -b feature/your-amazing-feature

# 3. Make changes and commit
git commit -m 'Add: description of your feature'

# 4. Push to your fork
git push origin feature/your-amazing-feature

# 5. Open Pull Request on GitHub

Code Quality Standards

  • Follow Dart style guide
  • Write tests for new features
  • Update documentation
  • Run flutter analyze before submitting
  • Ensure 80%+ code coverage for new code

Testing

# Run all tests
flutter test

# Run specific test file
flutter test test/models/simulator/board_test.dart

# Generate coverage
flutter test --coverage

📝 License

This project is licensed under the MIT License

What this means:

  • ✅ Free to use, modify, and distribute
  • ✅ Must include original license notice
  • ✅ No warranty provided
  • ✅ Attribution appreciated but not required

See LICENSE file for full details.


📞 Support & Feedback

Getting Help

  • 📧 Email: [your-email@example.com]
  • 🐛 GitHub Issues: Report bugs or request features
  • 💬 Discussions: Community Q&A and feedback

Report a Bug

When reporting issues, please include:

- Device model and OS version
- Flutter version (run: flutter --version)
- Steps to reproduce the issue
- Expected vs actual behavior
- Screenshots or error logs

📚 Additional Resources

Official Documentation

Educational


🙏 Credits & Acknowledgments

Design & Graphics

  • Freepik - Free-to-use UI graphics and design assets
  • Custom Assets - Original artwork by development team
  • Poetsenone Font - Open-source font family

Technology

  • Flutter & Dart Teams - Exceptional framework and language
  • Open Source Community - All package maintainers and contributors
  • GetX Community - Amazing reactive programming framework

Testing & Feedback

  • Community members who tested and provided feedback
  • Bug reporters and feature request contributors
  • All supporters of this project

⚖️ FINAL COMPREHENSIVE LEGAL STATEMENT

IMPORTANT - PLEASE READ COMPLETELY

Non-Affiliation Notice

This application is created by independent hobbyist developer(s) and is:

  • NOT affiliated with any video game company or publisher
  • NOT endorsed or approved by any game developer
  • NOT connected to, derived from, or part of any original game
  • NOT authorized to use any proprietary game mechanics or IP

This is a fan-made educational and entertainment tool only.

Terms of Use - Binding Agreement

By using this application, you agree to:

  1. Non-Commercial Use - Use only for personal entertainment and learning
  2. Accept All Risks - Developer provides NO warranty or liability guarantees
  3. Accuracy Disclaimer - Results are estimates and NOT guaranteed outcomes
  4. No Competitive Use - Do not use in official competitions or for commercial advantage
  5. Respect IP Rights - All game IP belongs to respective copyright holders
  6. Follow Game ToS - This tool doesn't violate any game terms of service
  7. Retain Disclaimers - Any distributions must include all original notices

Copyright & Intellectual Property

  • All referenced game content remains owned by respective publishers
  • Original code and assets created for this project are licensed under MIT
  • No proprietary game information has been used
  • All third-party content is properly licensed and credited

Limitation of Liability

The developer/creators of this application:

  • Are NOT responsible for any consequences of using this tool
  • DO NOT guarantee accuracy, functionality, or results
  • DO NOT provide warranty of any kind, express or implied
  • WILL NOT be liable for damages, losses, or inconvenience
  • DISCLAIM ALL LIABILITY under applicable law

Use at your own risk. Results are for estimation only.

Dispute Resolution

If you are the copyright holder of any content in this project and believe your rights are violated:

  1. Contact immediately at [your-email@example.com]
  2. Provide evidence of copyright ownership
  3. Request specific action (modification, removal, etc.)
  4. Allow reasonable time for resolution

Severability

If any part of these terms is found invalid or unenforceable, all other valid parts remain in effect.


Version: 1.0
Last Updated: November 2025
Status: Active & Maintained

Made with ❤️ by an indie developer
Not affiliated with any video game company
Please use responsibly and ethically.

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors