Ren’Py Relations

English · 简体中文

An embeddable Python library for relational facts and compiled Logica rules, with optional Ren’Py integration.

Story conditions often recur across encounters: access to a place, knowledge of a secret, or an earlier choice. Ren’Py Relations lets you name and compose those conditions as rules. Actions change facts; scripts query which actions or encounters are available. The same core works in ordinary Python applications.

Logica compiles rules to SQL during development. SQLite or DuckDB stores facts and evaluates queries at runtime. The Ren’Py adapter connects fact snapshots to save, load, and rollback.

A small example

The shipped Palace rules derive archive access from sponsorship or faction membership:

from renpy_relations import LogicDB

logic = LogicDB("examples/palace/game/relations.rules.json")
try:
    logic.add("Sponsor", character="hero", location="archive")
    print(logic.query("CanEnter", character="hero"))
    # [{'character': 'hero', 'location': 'archive'}]
finally:
    logic.close()

Run from the source root after the quickstart setup. No hand-written SQL is needed for this example.

world.l + schema.json
        │ renpy-relations-compile (during development)
        ▼
backend-specific JSON rule bundle
        │ LogicDB (during the game)
        ▼
facts → derived answers → script choices and effects
        │ Ren’Py adapter publishes fact snapshots
        ▼
Ren’Py snapshot variable → save / load / rollback

The runtime uses cached mode by default: it builds derived relations when first queried and invalidates affected results after fact changes. SQLite and DuckDB are available, with separate compiled bundles for each. The reference explains the other query modes and their tradeoffs.

Choose a starting point

Installation

In a Python application:

uv add renpy-relations

From a source checkout:

uv sync --locked

Follow the Python guide to install a wheel or embed the library, or the Ren’Py quickstart to stage a game. Development uses Python 3.12; supported environments and driver versions are listed in the reference.

For SQL sorting, aggregation, and joins over facts and derived relations, see query_sql().

Project layout

Foundations and license

Learn more through the official Logica user guide and SQLite overview. Logica compiles rules during development; games run the compiled SQL and do not need the Logica compiler.

Project code, example scripts, documentation, and original example data use the MIT license. Dependencies, the Tidelight font, and distributed Ren’Py runtimes retain their own licenses; see third-party notices.