109 lines
4.3 KiB
Markdown
109 lines
4.3 KiB
Markdown
# NuCon (Nucleares Controller)
|
|
|
|
NuCon is a Python library designed to interface with and control parameters in Nucleares, a nuclear reactor simulation game. It provides a robust, type-safe foundation for reading and writing game parameters, allowing users to easily create their own automations and control systems.
|
|
|
|
In future versions, NuCon aims to implement built-in automation features.
|
|
|
|
## Features
|
|
|
|
- Enum-based parameter system for type safety and code clarity
|
|
- Support for various parameter types including floats, integers, booleans, strings, and custom enums
|
|
- Read and write capabilities for game parameters
|
|
- Custom truthy values for status enums to simplify conditional logic
|
|
- Dummy mode for testing without connecting to the game
|
|
- Batch operations for getting multiple parameters at once
|
|
|
|
## Installation
|
|
|
|
To install NuCon, clone this repository and install via pip:
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
## Usage
|
|
|
|
Here's a basic example of how to use NuCon:
|
|
|
|
```python
|
|
from nucon import Nucon, BreakerStatus
|
|
|
|
# Set the base URL for the game's API (if different from default)
|
|
Nucon.set_base_url("http://localhost:8080/")
|
|
|
|
# Enable dummy mode for testing (optional)
|
|
Nucon.set_dummy_mode(True)
|
|
|
|
# Read a parameter
|
|
core_temp = Nucon.CORE_TEMP.value
|
|
print(f"Core Temperature: {core_temp}")
|
|
|
|
# Read a parameter with an enum type
|
|
pump_status = Nucon.COOLANT_CORE_CIRCULATION_PUMP_0_STATUS.value
|
|
print(f"Pump 0 Status: {pump_status}")
|
|
|
|
# Write to a parameter
|
|
Nucon.GENERATOR_0_BREAKER.value = BreakerStatus.OPEN # or True
|
|
print(f"Generator 0 Breaker Status: {Nucon.GENERATOR_0_BREAKER.value}")
|
|
|
|
# Use custom truthy values
|
|
if Nucon.COOLANT_CORE_CIRCULATION_PUMP_0_STATUS.value:
|
|
print("Pump 0 is active")
|
|
```
|
|
|
|
## API Reference
|
|
|
|
The `Nucon` enum contains all available parameters. Each parameter is defined with:
|
|
- An ID (string)
|
|
- A type (float, int, bool, str, or a custom Enum)
|
|
- A boolean indicating whether it's writable
|
|
|
|
Parameter properties:
|
|
- `Nucon.<PARAMETER>.value`: Get or set the current value of the parameter. Assigning a new value will write it to the game.
|
|
- `Nucon.<PARAMETER>.param_type`: Get the type of the parameter
|
|
- `Nucon.<PARAMETER>.is_writable`: Check if the parameter is writable
|
|
- `Nucon.<PARAMETER>.enum_type`: Get the enum type of the parameter if it's an enum, otherwise None
|
|
|
|
Parameter methods:
|
|
- `Nucon.<PARAMETER>.read()`: Get the current value of the parameter (alias for `value`)
|
|
- `Nucon.<PARAMETER>.write(new_value, force=False)`: Write a new value to the parameter. `force` will try to write even if the parameter is known as non-writable.
|
|
|
|
Class methods:
|
|
- `Nucon.get(parameter)`: Get the value of a specific parameter. Also accepts string parameter names.
|
|
- `Nucon.set(parameter, value, force=False)`: Set the value of a specific parameter. Also accepts string parameter names.
|
|
- `Nucon.get_all_readable()`: Get a list of all readable parameters (which is all parameters)
|
|
- `Nucon.get_all_writable()`: Get a list of all writable parameters
|
|
- `Nucon.get_all()`: Get all parameter values as a dictionary
|
|
- `Nucon.get_multiple(params)`: Get values for multiple specified parameters
|
|
- `Nucon.set_base_url(url)`: Set the base URL for the game's API
|
|
- `Nucon.set_dummy_mode(dummy_mode)`: Enable or disable dummy mode for testing
|
|
|
|
Custom Enum Types:
|
|
- `PumpStatus`: Enum for pump status (INACTIVE, ACTIVE_NO_SPEED_REACHED, ACTIVE_SPEED_REACHED, REQUIRES_MAINTENANCE, NOT_INSTALLED, INSUFFICIENT_ENERGY)
|
|
- `PumpDryStatus`: Enum for pump dry status (ACTIVE_WITHOUT_FLUID, INACTIVE_OR_ACTIVE_WITH_FLUID)
|
|
- `PumpOverloadStatus`: Enum for pump overload status (ACTIVE_AND_OVERLOAD, INACTIVE_OR_ACTIVE_NO_OVERLOAD)
|
|
- `BreakerStatus`: Enum for breaker status (OPEN, CLOSED)
|
|
|
|
## Testing
|
|
|
|
NuCon includes a test suite to verify its functionality and compatibility with the Nucleares game.
|
|
|
|
### Running Tests
|
|
|
|
To run the tests:
|
|
|
|
1. Ensure the Nucleares game is running and accessible at http://localhost:8080/ (or update the URL in the test setup).
|
|
2. Install pytest: `pip install pytest`
|
|
3. Run the tests: `pytest test/test.py`
|
|
|
|
### Test Coverage
|
|
|
|
The tests verify:
|
|
|
|
- Parameter types match their definitions in NuCon
|
|
- Writable parameters can be written to
|
|
- Non-writable parameters cannot be written to, even when force-writing
|
|
- Enum parameters and their custom truthy values behave correctly
|
|
|
|
## Disclaimer
|
|
NuCon is an unofficial tool and is not affiliated with or endorsed by the creators of Nucleares.
|