Metadata-Version: 2.4
Name: larp-lib
Version: 0.8.0
Summary: Look like you know what you're doing.
Author: Montgomery Brown
License: MIT
Project-URL: Homepage, https://github.com/MintyTheCoder/larp-lib
Project-URL: Repository, https://github.com/MintyTheCoder/larp-lib
Project-URL: Documentation, https://github.com/MintyTheCoder/larp-lib/blob/main/docs/GUIDE.md
Project-URL: Changelog, https://github.com/MintyTheCoder/larp-lib/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/MintyTheCoder/larp-lib/issues
Keywords: terminal,cli,fun,prank,ascii,demo,simulation,incident,hacker,gui,tkinter
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Terminals
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# larp

Zero-dependency, stdlib-only terminal (and optional GUI) eye-candy. Loading
bars that go nowhere, fake boot sequences, matrix rain, glitch reveals,
live "metrics" dashboards, fabricated stack traces, a technobabble
generator, and a matching CLI. For demos, streams, screen recordings, and
anyone who needs to look extremely busy for four seconds.

## Two ways to use this

**No coding required** — run pre-built effects straight from a terminal:

```
pip install larp-lib
larp boot --name REACTOR
```

Full command list: **[docs/CLI.md](https://github.com/MintyTheCoder/larp-lib/blob/main/docs/CLI.md)**

**Write your own scripts** — import the library, call its functions with
your own content, and actually learn some Python while you do it:

```python
import larp

larp.banner("PROJECT CHIMERA")
larp.boot_sequence("CHIMERA", steps=["Linking libchimera.so", "Flashing bootloader"])
```

Full function reference + a from-scratch walkthrough: **[docs/GUIDE.md](https://github.com/MintyTheCoder/larp-lib/blob/main/docs/GUIDE.md)**

Short version of the difference: the CLI is larp's functions with the
arguments already filled in for you. Writing a script is filling them in
yourself.

## Install

```
pip install larp-lib
```

For local development: `pip install -e .` from the repo root.

## GUI

`from larp import gui` gets you fake installers, splash screens, toast
notifications, and a fullscreen BSOD gag — needs tkinter (bundled with
Windows/Mac Python, `sudo apt install python3-tk` on Linux). Covered in
[docs/GUIDE.md](https://github.com/MintyTheCoder/larp-lib/blob/main/docs/GUIDE.md#gui-vs-terminal) and [docs/CLI.md](https://github.com/MintyTheCoder/larp-lib/blob/main/docs/CLI.md#gui-requires-tkinter).

## Core simulation (0.5.0 foundation, 0.6.0 coordination)

Effects on their own are independent — call one, it runs, it's done.
`larp.core` and `larp.simulation` add shared state underneath them: a
`System` made of named `Subsystem`s, an `EventBus` those subsystems emit
onto when their state changes, a `Scheduler` for delayed/repeating/
event-triggered callbacks, and stateful `Telemetry`/`ProcessManager` that
hold values between calls instead of generating them fresh each time.

```python
import larp

system = larp.System("NEXUS")
db = system.add_subsystem("database", state="ONLINE")
system.subscribe("database.state_changed", lambda e: print(e.severity, e.message))

db.set_state("DEGRADED", bus=system.bus)   # prints: WARNING database ONLINE -> DEGRADED
```

`Incident` and `EventLog` build on that to make it actually coordinated —
a scripted escalation/recovery arc against a subsystem, captured live in
a filtered, timestamped log:

```python
system = larp.System("NEXUS")
system.add_subsystem("database", state="ONLINE")
log = larp.EventLog(system.bus, live=True, min_severity="NOTICE")

larp.Incident("DATABASE_DEGRADATION", system=system, subsystem="database").start()
```

And `telemetry_dashboard` wires the existing terminal dashboard effect to
a real `Telemetry` object instead of independent random numbers:

```python
telemetry = larp.Telemetry()
telemetry.add("cpu", initial=40, minimum=0, maximum=100, noise=6, unit="%")
larp.telemetry_dashboard(telemetry, duration=6, title="NEXUS")
```

`NetworkSimulator` gives you hosts with a fixed identity — same IP every
time, reused across scans and traffic instead of regenerated randomly
per call:

```python
net = larp.NetworkSimulator()
net.add_host("DB-04", ip="10.24.18.12", services={5432: "postgres"})
net.add_host("CACHE-17", ip="10.24.18.15", services={6379: "redis"})

print(net.scan(delay=0.5))
print(net.traffic(n=5, delay=0.5))
net.set_degraded("DB-04", packet_loss=0.9)   # next .scan() shows DB-04 filtered
```

`delay` makes it print live, line by line, instead of dumping the whole
result instantly — leave it at `0` (the default) when you just want the
string back for your own use.

`BuildSimulator` fixes a project's files, modules, and dependencies at
construction — every `.run()` compiles the same project instead of
regenerating a new one, and it can wire its result onto a `System`'s event bus:

```python
build = larp.BuildSimulator("NEXUS", num_files=14, num_dependencies=9)
build.run(delay=0.15)                     # success or failure, real pacing
build.run(delay=0.15, force_fail=True)    # same project, forced failure path
build.last_result                         # "success" or "failed"
```

See `demos/core_demo.py` (System/EventBus/Scheduler/Telemetry/ProcessManager),
`demos/incident_demo.py` (Incident, EventLog, telemetry_dashboard),
`demos/network_demo.py` (NetworkSimulator), and `demos/build_demo.py`
(BuildSimulator) for full walkthroughs.

## Demos

`demos/` has scripted showcases. `python demos/showcase.py [name|all]` runs
everything back to back — useful for recording a GitHub README gif.
`demos/core_demo.py`, `demos/incident_demo.py`, `demos/network_demo.py`, and
`demos/build_demo.py` cover the simulation layer separately, since it's
library-only (no CLI yet).
`demos/jargon_demo.py` covers the five jargon generators that don't have
their own CLI command (`term`, `commit_message`, `pr_title`, `var_name`,
`stack_trace` — only `babble` is CLI-exposed).

## Tests

```
pip install pytest
pytest
```

## Project layout

```
larp/
  effects.py    loading, boot_sequence, glitch_text, banner, countdown, notification
  terminal.py   hacker_typer, fake_terminal, matrix_rain, network_scan
  codegen.py    code_scroll, print_stack_trace, commit_log
  dashboard.py  dashboard, multi_progress
  jargon.py     babble, term, commit_message, pr_title, var_name, stack_trace
  gui.py        tkinter windows: installer, splash, dialog, bsod, terminal, matrix, toast, dashboard
  cli.py        argparse CLI wiring every function above, including gui-* subcommands
  core/         System, Subsystem, EventBus, Event, Scheduler, Context, EventLog, Incident
  simulation/   Telemetry, Metric, ProcessManager, Process, NetworkSimulator, Host, BuildSimulator
docs/
  CLI.md        every CLI command, its flags, and an example
  GUIDE.md      library usage, function reference, and a learn-to-code walkthrough
```
