ReeSaber Python Module

A comprehensive Python library for creating, managing, and exporting custom saber configurations for the Beat Saber ReeSaber mod.

Table of Contents

• Introduction
• Installation
• Module Structure
• Core Components
• Usage Examples
• API Reference
• Best Practices
• Troubleshooting

Introduction

ReeSaber is a Python library that provides a clean, object-oriented interface for creating and managing custom saber configurations for the Beat Saber ReeSaber mod. It allows users to:

• Create custom sabers with various visual effects
• Define color mappings and transitions
• Configure drivers to respond to gameplay mechanics
• Export configurations to compatible JSON files

The library uses Pydantic models for strict type checking and validation, ensuring configurations are always valid before export.

Installation

Requirements

• Python 3.8+
• PIL/Pillow (for image processing)
• Pydantic 2.0+

Installation Steps

# Using pip
pip install reesaber

# From source
git clone https://github.com/CodeSoftGit/reesaber-py.git
cd reesaber-py
pip install -e .

Module Structure

The ReeSaber module is organized into the following structure:

reesaber/
├── __init__.py              # Main exports
├── models/                  # Base data models
│   ├── __init__.py
│   ├── base.py              # Vector3, Color, Transform
│   ├── control.py           # ControlPoint, Mappings
│   └── driver.py            # Driver, DriverType
├── modules/                 # Saber modules
│   ├── __init__.py
│   ├── base.py              # Base module classes
│   ├── blur_saber.py        # BlurSaber implementation
│   ├── simple_trail.py      # SimpleTrail implementation
│   └── vanilla_saber.py     # VanillaSaber implementation
├── builder.py               # ReeSaberBuilder
├── config.py                # SaberConfig
└── utils.py                 # Utility functions

Core Components

Models

• Vector3: Represents a 3D vector for position, rotation, or scale
• Color: RGBA color representation with convenience methods
• Transform: Position, rotation, and scale in 3D space
• ControlPoint: Time and value pairs for interpolation
• Driver: Maps gameplay parameters to visual effects

Modules

• BlurSaber: Creates a saber with blur effects and customizable properties
• SimpleTrail: Creates a trail effect behind the saber
• VanillaSaber: Recreates the standard Beat Saber saber

Configuration

• SaberConfig: Manages complete saber configurations with multiple modules
• ReeSaberBuilder: Fluent interface for creating saber configurations

Usage Examples

Basic Usage

from reesaber import ReeSaberBuilder, Color

# Create a basic red saber with trail
config = (
    ReeSaberBuilder()
    .add_blur_saber("Red Saber", Color.red(), length=1.2, glow=1.5)
    .add_trail("Red Trail", Color.red(), length=0.25)
    .build()
)

# Export the configuration
config.export("my_red_saber.json")

Creating a Custom Saber

from reesaber import BlurSaber, Color, ControlPoint, Vector3, Transform

# Create a custom positioned blue saber
saber = BlurSaber.create("Blue Saber", Color.blue(), length=1.0, glow=2.0)

# Customize position
saber.config.local_transform = Transform(
    position=Vector3(x=0.0, y=0.05, z=-0.1),
    rotation=Vector3(x=0.0, y=0.0, z=5.0)
)

# Create a configuration and add the saber
from reesaber import SaberConfig
config = SaberConfig()
config.add_module(saber)
config.export("blue_saber.json")

Creating a Rainbow Saber

from reesaber import create_rainbow_saber

# Create a rainbow saber
rainbow_config = create_rainbow_saber("Rainbow Saber")
rainbow_config.export("rainbow_saber.json")

Creating Sabers from an Image

from reesaber import SaberConfig

# Create a configuration from a pixel art image
config = SaberConfig()
config.create_from_image(
    "pixel_art.png",
    pixel_size=0.02,
    spacing=0.005
)
config.export("pixel_art_saber.json")

API Reference

Color

# Create colors
red = Color.red()                          # Predefined red
blue = Color(r=0.0, g=0.0, b=1.0, a=1.0)   # Manual blue
green = Color.from_rgb(0, 255, 0)          # From RGB (0-255)

Vectors and Transforms

# Create a position vector
position = Vector3(x=0.0, y=0.1, z=-0.2)

# Create a transform
transform = Transform(
    position=Vector3(x=0.0, y=0.1, z=-0.2),
    rotation=Vector3(x=0.0, y=0.0, z=10.0),
    scale=Vector3(x=1.0, y=1.0, z=1.0)
)

Drivers

from reesaber import Driver, DriverType, Color

# Create a velocity-based driver
driver = Driver(
    driver_type=DriverType.TIP_VELOCITY,
    increase_resistance=0.1,
    decrease_resistance=0.5
)

# Or use the convenience method
driver = Driver.velocity_driver(Color.red())

SaberConfig

from reesaber import SaberConfig, BlurSaber, SimpleTrail, Color

# Create a configuration
config = SaberConfig()

# Add modules
config.add_module(BlurSaber.create("Main Saber", Color.red()))
config.add_module(SimpleTrail.create("Trail", Color.red()))

# Export
config.export("my_saber.json")

ReeSaberBuilder

from reesaber import ReeSaberBuilder, Color

# Create a configuration using the builder
config = (
    ReeSaberBuilder()
    .add_blur_saber("Main Saber", Color.red())
    .add_trail("Trail", Color.red())
    .add_vanilla_saber("Vanilla Saber", with_trail=True)
    .build()
)

Best Practices

1. Use the Builder Pattern: For most cases, the ReeSaberBuilder provides the simplest and most readable approach.

2. Start Simple: Begin with basic sabers and add complexity incrementally.

3. Validate Configurations: Always test your configurations in-game to ensure they look as expected.

4. Optimize Image-Based Sabers: When creating sabers from images, use small images (32x32 or less) to avoid performance issues.

Troubleshooting

Common Issues

1. Sabers Not Appearing In-Game

   • Ensure the JSON file is in the correct folder
   • Check for JSON formatting errors
   • Verify the ReeSaber mod is properly installed

2. Incorrect Colors

   • Use the Color.from_rgb() method for proper colors

3. Performance Issues

   • Reduce the number of modules
   • Lower resolution settings

Debugging

Enable logging to track the module's actions:

from reesaber import configure_logging
import logging

# Configure logging
configure_logging(level=logging.DEBUG)

License

This project is licensed under the MIT License - see the LICENSE file for details.