Metadata-Version: 2.4
Name: flcpy
Version: 0.3.0
Summary: Python control interface for Flare Live / Flare Real
Author-email: Jiwei Wang <zmh78879@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Flare Python Controller (flcpy)

Python networking interface for Flare Live / Flare Real.

## Install & Upgrade

```
pip install --upgrade flcpy
```

## Use

```
import flcpy

s = flcpy.connect()  # Connect only; does not clear simulation or recover the World.
obj = s.get_object(...)
...
```

### Temporary experiments

With a current Flare Live server, explicitly begin an experiment before making
temporary scene edits. Clear simulation before ending the experiment:

```python
import flcpy

s = flcpy.connect()
try:
    if not s.begin_experiment():
        raise RuntimeError("Could not begin experiment; see the Flare Live log")
    try:
        # Clone objects, randomize properties, etc. These edits stay temporary.
        # s.start() initializes simulation; s.simulate(...) advances it.
        ...
    finally:
        s.clear()  # Required if simulation was initialized.
        s.end_experiment()  # Discard temporary edits and return to the document.
finally:
    s.close()
```

`begin_experiment()` and `end_experiment()` return `True` on success and `False`
on failure; failure details appear in the Flare Live log. They do not implicitly
initialize or clear simulation. Without an experiment, scene edits affect the
Document World and participate in its undo/redo history.

`recover_world()` is retained for older Flare Live servers. Both `connect()`
and `Simulator()` now default to `recover_world=False`. For an older server,
explicitly pass `recover_world=True` to retain the previous clear-and-recover
behavior on connection. Modern servers reject recovery; use experiments instead.

### Tests

Run the dependency-free client contract tests from this repository:

```sh
python -m unittest discover -s tests -v
```
