Voodoo Box - CS2 Faceit

A modular utility collection extracted from my earlier personal projects 'extendo' and 'NadeStacked', their combined ambition as described below: "a Chrome extension with a Flask + MongoDB backend to turn every Faceit CS2 match-room into an instant scouting report—map-veto advice, player dossiers, utility habits—all before the knife round ends."

Story: Faceit API regulations set stop for the project, since it relied mainly on downloading and parsing demos. However, I recently got access to the Faceit Demo API, so I picked out the core functionality modules from my previous attempts and put them here. Not sure where I'm going from here...

TLDR: This repository contains reusable code components organized by functionality, making it easy to integrate proven solutions into new projects.

Project Structure

voodoo-box/
├── api/              # API clients and HTTP utilities
├── data/             # Data processing and transformation
├── files/            # File management and I/O operations  
├── web/              # Browser extension and web utilities
├── gaming/           # Gaming-specific utilities (CS2 demos)
└── utils/            # Cross-cutting utilities (logging, caching, error handling)

Philosophy

Modular: Each directory focuses on a specific domain of functionality Reusable: Code designed to work across different projects and contexts
Well-documented: Clear usage examples and integration patterns Battle-tested: Extracted from working production code

[>>] Quick Start

The voodoo-box can be used as a complete package or individual modules:

# Quick setup for new projects
from voodoo_box import quick_setup

utils = quick_setup("my_project", enable_debug=True)
logger = utils['logger']
logger.info("Project started")

# Or use individual modules
from voodoo_box.api.faceit_client import FaceitClient
from voodoo_box.utils.caching import TimedLRUCache

@TimedLRUCache(maxsize=64)
def get_player_data(player_id):
    client = FaceitClient(api_key="your_key")
    return client.get_player_stats(player_id)

Module Overview

• api/: Robust HTTP clients with retry logic and error handling
• data/: Statistical aggregation, data cleaning, and transformation utilities
• files/: File management, JSON handling, and organized output systems
• web/: Browser extension utilities, DOM manipulation, and page interaction
• gaming/: CS2 demo analysis, position tracking, and gaming data processing
• utils/: Cross-cutting utilities for logging, caching, and error handling

Installation & Usage

The voodoo-box is designed to be copied into your project or imported as a local package:

# Check module availability
from voodoo_box import print_module_status
print_module_status()

# Get module information programmatically
from voodoo_box import get_module_info
modules = get_module_info()

Documentation

See individual module READMEs for detailed usage instructions:

• API Module - HTTP clients and API utilities
• Data Module - Data processing and aggregation
• Files Module - File management and I/O
• Web Module - Browser extension utilities
• Gaming Module - CS2 demo analysis
• Utils Module - Logging, caching, and error handling

Key Features

• Zero external dependencies for core utilities
• Comprehensive logging with colored console output and JSON file logging
• Performance monitoring with caching and timing utilities
• Robust error handling with retry logic and circuit breakers
• Cross-platform compatibility (Windows/Unix)
• Production-ready code extracted from working projects

Integration Patterns

# Example: Full-featured application setup
from voodoo_box import quick_setup
from voodoo_box.api.faceit_client import FaceitClient
from voodoo_box.data.stats_aggregators import StatsAggregator
from voodoo_box.files.file_manager import FileManager

# Initialize utilities
utils = quick_setup("esports_analyzer")
logger = utils['logger']

# Set up components with integrated error handling and caching
@utils['cache'](maxsize=128)
@utils['retry'](max_attempts=3)
def fetch_and_process_player_data(player_id):
    with utils['error_handler'].ExceptionContext({"player_id": player_id}):
        # Fetch data
        client = FaceitClient()
        raw_data = client.get_player_stats(player_id)
        
        # Process data
        aggregator = StatsAggregator()
        processed_data = aggregator.aggregate_player_stats(raw_data)
        
        # Save results
        file_manager = FileManager()
        file_manager.save_json(f"player_{player_id}.json", processed_data)
        
        logger.info(f"Successfully processed player {player_id}")
        return processed_data

Source Projects

These modules were extracted and enhanced from:

• extendo: Chrome extension + Flask backend for CS2 match analysis
• NadeStacked: CS2 demo parsing and position heatmap generation

Each module maintains the proven patterns from the original projects while being refactored for maximum reusability.