ttyengine 0.1.0__tar.gz → 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {ttyengine-0.1.0 → ttyengine-0.2.0}/PKG-INFO +125 -6
- {ttyengine-0.1.0 → ttyengine-0.2.0}/README.md +124 -5
- {ttyengine-0.1.0 → ttyengine-0.2.0}/pyproject.toml +1 -1
- ttyengine-0.2.0/tests/test_engine.py +1579 -0
- ttyengine-0.2.0/tests/test_net.py +967 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine/__init__.py +7 -3
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine/ascii_styler.py +23 -9
- ttyengine-0.2.0/ttyengine/components/__init__.py +14 -0
- ttyengine-0.2.0/ttyengine/components/force.py +189 -0
- ttyengine-0.2.0/ttyengine/components/humanoid.py +828 -0
- ttyengine-0.2.0/ttyengine/components/inherit.py +161 -0
- ttyengine-0.2.0/ttyengine/components/joint.py +1249 -0
- ttyengine-0.2.0/ttyengine/components/light.py +598 -0
- ttyengine-0.2.0/ttyengine/components/pen.py +271 -0
- ttyengine-0.2.0/ttyengine/components/physics.py +876 -0
- ttyengine-0.2.0/ttyengine/components/shared.py +194 -0
- ttyengine-0.2.0/ttyengine/components/transform.py +1404 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine/compositor.py +15 -15
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine/errors.py +57 -1
- ttyengine-0.2.0/ttyengine/input_handler.py +1539 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine/launcher.py +11 -4
- ttyengine-0.2.0/ttyengine/net/__init__.py +18 -0
- ttyengine-0.2.0/ttyengine/net/codec.py +301 -0
- ttyengine-0.2.0/ttyengine/net/errors.py +10 -0
- ttyengine-0.2.0/ttyengine/net/layers.py +367 -0
- ttyengine-0.2.0/ttyengine/net/node.py +531 -0
- ttyengine-0.2.0/ttyengine/net/sync.py +753 -0
- ttyengine-0.2.0/ttyengine/net/transport.py +543 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine/scene.py +28 -7
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine.egg-info/PKG-INFO +125 -6
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine.egg-info/SOURCES.txt +19 -2
- ttyengine-0.1.0/tests/test_engine.py +0 -652
- ttyengine-0.1.0/ttyengine/components.py +0 -4718
- ttyengine-0.1.0/ttyengine/input_handler.py +0 -814
- {ttyengine-0.1.0 → ttyengine-0.2.0}/LICENSE +0 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/setup.cfg +0 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/tests/test_smoke.py +0 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine/ansi.py +0 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine/figlet-LICENSE.txt +0 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine/figlet.py +0 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine/fonts.zip +0 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine/image_reader.py +0 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine/region.py +0 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine/sound.py +0 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine/terminal.py +0 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine.egg-info/dependency_links.txt +0 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine.egg-info/requires.txt +0 -0
- {ttyengine-0.1.0 → ttyengine-0.2.0}/ttyengine.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: ttyengine
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.2.0
|
|
4
4
|
Summary: A terminal rendering, physics and sound engine
|
|
5
5
|
Project-URL: Homepage, https://github.com/asard6348/tty-engine
|
|
6
6
|
Project-URL: Source, https://github.com/asard6348/tty-engine
|
|
@@ -65,7 +65,7 @@ Build animated, interactive scenes out of text, with collisions, joints, lightin
|
|
|
65
65
|
TTY Engine draws everything as styled text and updates the terminal once per frame. Objects are assembled from small components, which are attached automatically based on the keyword arguments you pass when creating them. A box of text becomes a physics body as soon as you give it a velocity, and a light source as soon as you give it a light.
|
|
66
66
|
|
|
67
67
|
- **No dependencies.** Image decoding (PNG, JPEG, GIF, BMP, PNM; many more when ffmpeg is installed), FIGlet text, the audio mixer and the terminal and input handling are all implemented in the standard library.
|
|
68
|
-
- **Component-based objects.** `transform`, `
|
|
68
|
+
- **Component-based objects.** `transform`, `physics`, `pen`, `force`, `joint` and `light` cover position and style, collisions, drawing, area forces, linked bodies and lighting.
|
|
69
69
|
- **Rich text output.** Truecolor, transparency and fades, bundled FIGlet fonts, and image-to-text conversion.
|
|
70
70
|
- **Input and sound included.** Keyboard and mouse input with press, release and held states, plus a built-in mixer with a small synthesizer.
|
|
71
71
|
- **Simple structure.** Write a class (or just a function) with `start`, `update` and `final` methods, and hand it to `start()`.
|
|
@@ -266,17 +266,17 @@ Mouse positions are reported in terminal cells counted from the top-left. With t
|
|
|
266
266
|
|
|
267
267
|
|
|
268
268
|
|
|
269
|
-
An object starts out empty. `create()` looks at its keyword arguments, attaches the components that own them, and passes each value on. `transform`
|
|
269
|
+
An object starts out empty. `create()` looks at its keyword arguments, attaches the components that own them, and passes each value on. `transform` is always attached; the others are added the first time you use one of their settings.
|
|
270
270
|
|
|
271
271
|
| Component | Added when you pass | What it does |
|
|
272
272
|
|---|---|---|
|
|
273
|
-
| `transform` | always | Position, text, colors, opacity, rotation, flipping, shadow. |
|
|
274
|
-
| `rendering` | always | Visibility (`show`), drawing order (`z`) and whether spaces are drawn (`spaces`). |
|
|
273
|
+
| `transform` | always | Position, text, colors, opacity, rotation, flipping, shadow, visibility (`show`), drawing order (`z`) and whether spaces are drawn (`spaces`). |
|
|
275
274
|
| `physics` | `xvel`, `yvel`, `bounciness`, `gravity`, `friction`, `mass`, `phantom`, ... | Velocity, collisions, bouncing, friction and touch callbacks. |
|
|
276
275
|
| `pen` | `pen={...}` | Paints characters at a point relative to the object. Settings: `char`, `x`, `y`, `radius`, `shape`. |
|
|
277
276
|
| `force` | `force=...` or `force={...}` | Pushes other objects, optionally limited by a radius or a filter. Settings: `strength`, `affect`, `cap`, `position`, `radius`, `torque`, `shield`. |
|
|
278
|
-
| `joint` | `preset`, `joints`, `elasticity`, `kind`, ... | Links objects together as a rope, rod, spring, hinge, slider or fixed joint. |
|
|
277
|
+
| `joint` | `preset`, `joints`, `elasticity`, `kind`, `limit`, `target`, ... | Links objects together as a rope, rod, spring, hinge, slider or fixed joint. A pinned `ball` joint can also limit and motor the follower's rotation with `limit`, `target`, `gain` and `effort`. |
|
|
279
278
|
| `light` | `light=True` or `light={...}` | Turns the object into a light source. Settings: `color`, `alpha`, `radius`, `falloff`, `shadows`, `cone`, `direction`, `glow` and more. `scene.ambient` sets the base brightness. |
|
|
279
|
+
| `humanoid` | `humanoid={'parts': {...}}` | Builds a posable figure from a graph of parts, with the object as its root part. Settings: `parts`, `solid`, `physics`, `style`, `joints`, `poses`, `cycles`, `axis`, `elasticity`, `spaces`. |
|
|
280
280
|
|
|
281
281
|
Settings can be given flat, or grouped under the component's name. The two calls below are equivalent:
|
|
282
282
|
|
|
@@ -413,6 +413,7 @@ floor = scene.obj().create('#' * 40, 0, -10, dynamic=False) # immovable
|
|
|
413
413
|
| `mass` | Defaults to the number of visible characters. |
|
|
414
414
|
| `gravity` | An `(x, y)` pair that overrides the scene's gravity for this object. |
|
|
415
415
|
| `drag` | Overrides the scene's drag for this object. |
|
|
416
|
+
| `bouncethreshold` | Impact speed below which a collision does not bounce. Defaults to `scene.bouncethreshold` (`0.25`); set it to `0` to let shallow impacts bounce. When two bodies disagree, the lower value wins. |
|
|
416
417
|
|
|
417
418
|
**Reacting to contact.** Two tools cover the two common cases:
|
|
418
419
|
|
|
@@ -432,6 +433,74 @@ player.physics.ontouch(entered)
|
|
|
432
433
|
|
|
433
434
|
`ontouch(callback, when=None, once=False)` accepts a `when(other)` filter and can be limited to a single call with `once=True`.
|
|
434
435
|
|
|
436
|
+
`ontouch` fires when one body moves into another. A body that is only resting against, or pushed against by, another body does not trigger it, so use `touch`, `sides` and `grounded` for that case.
|
|
437
|
+
|
|
438
|
+
**Headings and bouncing.** `transform.forward` and `transform.bounce` use the object's `rotation` as the heading unless you pass `angle=`. Assigning the result to `rotation` also turns the sprite and its collision cells, so keep a separate heading and pass it as `angle` when the object should not rotate:
|
|
439
|
+
|
|
440
|
+
```python
|
|
441
|
+
heading = ball_heading # your own variable, in degrees
|
|
442
|
+
if ball.transform.approaching(normal, angle=heading): # True when moving into the surface
|
|
443
|
+
heading = ball.transform.bounce(normal, angle=heading)
|
|
444
|
+
heading = ball.transform.bounce(normal, angle=heading, incoming_only=True) # same check in one call
|
|
445
|
+
dx, dy = ball.transform.forward(1, angle=heading)
|
|
446
|
+
```
|
|
447
|
+
|
|
448
|
+
</details>
|
|
449
|
+
|
|
450
|
+
<details>
|
|
451
|
+
<summary><b>Humanoid figures</b></summary>
|
|
452
|
+
|
|
453
|
+
|
|
454
|
+
|
|
455
|
+
A `humanoid` component turns an object into the root of a jointed, posable figure. A figure is a graph of parts: every part is built from the text you give it, one part has no parent and becomes the object itself, and every other part hangs off a parent through a joint. Nothing is built in, so the same component makes people, spiders, robots or trees.
|
|
456
|
+
|
|
457
|
+
```python
|
|
458
|
+
parts = {
|
|
459
|
+
'torso': '###\n###\n###',
|
|
460
|
+
'head': {'text': 'O', 'parent': 'torso', 'at': 'top', 'joint': 'neck'},
|
|
461
|
+
'left_arm': {'text': '|\n|\n|', 'parent': 'torso', 'at': 'top_left', 'pin': 'top', 'shift': (-0.5, 0),
|
|
462
|
+
'joint': 'shoulder', 'group': 'arm'},
|
|
463
|
+
'right_arm': {'mirror': 'left_arm'},
|
|
464
|
+
'left_thigh': {'text': '|\n|\n|', 'parent': 'torso', 'at': 'bottom_left', 'pin': 'top', 'shift': (0.5, 0),
|
|
465
|
+
'joint': 'hip', 'group': 'thigh', 'density': 10},
|
|
466
|
+
'right_thigh': {'mirror': 'left_thigh', 'flip': False},
|
|
467
|
+
'left_shin': {'text': '|\n|\n|', 'parent': 'left_thigh', 'joint': 'knee', 'group': 'shin',
|
|
468
|
+
'density': 10},
|
|
469
|
+
'right_shin': {'mirror': 'left_shin', 'flip': False},
|
|
470
|
+
}
|
|
471
|
+
poses = {'arms_out': {'arm': 90}, 'crouch': {'thigh': -60, 'shin': 100}}
|
|
472
|
+
cycles = {'walk': {'left_thigh': {'amp': -32}, 'right_thigh': {'amp': 32}, 'arm': {'amp': 35}}}
|
|
473
|
+
body = scene.obj().create(None, 20, -10, humanoid={'parts': parts, 'poses': poses, 'cycles': cycles})
|
|
474
|
+
figure = body.humanoid
|
|
475
|
+
|
|
476
|
+
figure.apply_pose('arms_out') # poses and cycles are plain dicts: figure.poses, figure.cycles
|
|
477
|
+
figure.pose('arms_out') # a registered pose name works too
|
|
478
|
+
figure.pose({'left_thigh': -30}) # angles are degrees from the rest pose, clamped to joint limits
|
|
479
|
+
figure.velocity = (0.2, None) # moves every part together
|
|
480
|
+
figure.animate('walk', phase) # call each frame with a growing phase
|
|
481
|
+
figure.jump(0.6) # only while grounded
|
|
482
|
+
figure.detach('left_shin') # frees a part and everything attached to it
|
|
483
|
+
figure.ragdoll() # releases every joint; figure.ragdoll(False) stiffens them again
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
**Placement.** A part is placed by two anchors that meet at its joint: `at` is a point on the parent and `pin` is a point on the part itself. An anchor is a name (`top`, `bottom`, `left`, `right`, `center`, `top_left`, `top_right`, `bottom_left`, `bottom_right`) or an `(x, y)` pair of fractions of the part's size. `at` defaults to `bottom` and `pin` defaults to the opposite point, so a part sits against the parent on the side of its anchor. `shift=(dx, dy)` moves the joint in cells. The part is snapped to whole cells and the joint sits exactly on its `pin`.
|
|
487
|
+
|
|
488
|
+
**Mirroring.** `{'mirror': 'name'}` reflects another part across the vertical centre line of the root (or of the part named by the `axis` setting), inherits its text, `density`, `solid`, `z`, `physics`, `style`, `group` and joint, and hangs from the mirror of the source's parent unless `parent` is given. A mirrored joint has its limits and rest angle reversed, and so do the angles you pass through a group name; set `flip` to `False` to keep the same direction on both sides.
|
|
489
|
+
|
|
490
|
+
**Naming.** A pose, cycle, `style`, `get`, `set_text` or `remove_part` key is a part name or a `group`. Every part belongs to a group with its own name and to any `group` names it lists (a string or a list), and mirrored parts share the groups of their source. An exact part name sets the raw angle; a group name applies it with the sign flip of each member.
|
|
491
|
+
|
|
492
|
+
**Joints.** `joint` is a preset name from `joint.presets` or a dict of joint settings (`range`, `rest`, `elasticity`, `durability`, ...). The default is `hinge`. The `joints` setting overrides joints by group or part name.
|
|
493
|
+
|
|
494
|
+
**Ragdoll.** `figure.ragdoll(on=True, solid=None, limits=True)` turns every pose-driven joint into a free hinge that keeps its length, so the figure collapses under gravity and swings with impacts. `solid=True` forces every part to collide with the world while it is limp, while the default `None` keeps each part's own `solid` setting, and `limits=True` keeps the joint ranges. While limp, `pose` and `animate` do nothing; `ragdoll(False)` stiffens the joints in their current angles, after which `pose` works again. `figure.ragdolled` tells the current state.
|
|
495
|
+
|
|
496
|
+
**Elasticity.** The `elasticity` setting is optional and means what it means for every `joint`: unset, each joint keeps the joint default of `1`; set, it is the default for all joints of the figure, and a `joint` dict or the `joints` setting can still override it per part or group. Standing and limp figures use the same value. Values slightly above `1` soften the correction and can remove the sub-cell wobble a heavy standing figure may keep at exactly `1`, and values above about `3` make the figure sag.
|
|
497
|
+
|
|
498
|
+
**Limp figures.** A ragdoll's limbs are real rigid bodies: each limb is a ball joint pinned at its attach point with its own mass, moment of inertia and angular velocity, and the joint limits are angular impulses between the two bodies, so spin and momentum are conserved and only contacts and friction remove energy. `elasticity` sets how firmly the pins pull back together, as it does for every other joint of the figure.
|
|
499
|
+
|
|
500
|
+
**Cycles.** A cycle channel is `bias + amp * sin(phase + shift)`, or a bare number for `amp`; `rectify=True` clamps the sine to positive values. `figure.sample(cycle, phase, scale=1.0)` returns the angles and `figure.animate(cycle, phase, weight=1.0, scale=1.0)` applies them.
|
|
501
|
+
|
|
502
|
+
**Other part settings.** `text`, `parent`, `at`, `pin`, `shift`, `joint`, `mirror`, `flip`, `group`, `density` (mass per non-blank cell), `solid`, `z`, `physics`, `style` and `spaces`. `spaces` (default `False`, also a humanoid setting) makes a part's size ignore a trailing newline like the renderer does; with `spaces=True` the empty last line counts as a row, so `'█\n' * 3` is four rows tall and whatever hangs from it sits one row lower. A part's `solid` is unset by default and then follows the figure's `solid`, whose default `None` makes every part collide with the world; `solid=False` on a part keeps it from ever colliding and `solid=True` makes it always collide. The figure's `solid` can also be a bool or a list of part or group names. The parts of one figure never collide with each other. `add_part(name, spec)` and `add_parts({...})` grow a figure later.
|
|
503
|
+
|
|
435
504
|
</details>
|
|
436
505
|
|
|
437
506
|
<details>
|
|
@@ -469,6 +538,7 @@ session.style('tint', color=(255, 80, 120), bgcolor='darkblue')
|
|
|
469
538
|
- **FIGlet fonts** are bundled. `session.styler.fonts()` lists them, and `font=` accepts any name from that list.
|
|
470
539
|
- **Shapes** are available through `session.styler.shapes`: `circle`, `ellipse`, `block`, `triangle`, `diamond` and `line`.
|
|
471
540
|
- **Images** are converted to text with `session.styler.image(path, width=..., height=...)`. PNG, JPEG, GIF, BMP and PNM are decoded by the engine itself, and other formats (WebP, TIFF, TGA, ...) are decoded through ffmpeg when it is available. If you give neither `width` nor `height`, the image is `80` columns wide (or its own pixel width, if that is smaller), so the result is the same on every terminal.
|
|
541
|
+
`shades` is the string of characters from darkest to brightest, and defaults to a 256-step gradient from a space to `█`. It is plain monochrome unless you pass `color=True`, and `bgcolor=` (a name or `(r, g, b)`) fills every cell with that background and blends transparent pixels into it.
|
|
472
542
|
|
|
473
543
|
```python
|
|
474
544
|
ring = session.styler.shapes.circle(5)
|
|
@@ -635,6 +705,55 @@ The older names keep working: `termxoffset`, `termyoffset`, `termwidth` and `ter
|
|
|
635
705
|
|
|
636
706
|
</details>
|
|
637
707
|
|
|
708
|
+
<details>
|
|
709
|
+
<summary><b>Networking: UDP, TCP, servers and peer-to-peer</b></summary>
|
|
710
|
+
|
|
711
|
+
|
|
712
|
+
|
|
713
|
+
`ttyengine.net` shares a running simulation between processes over TCP, UDP or both, using only the standard library. A `Node` is one participant: it can listen (`host`), connect (`connect`) or do both, so the same code builds a dedicated server, a client, or a peer-to-peer mesh. A `Sync` shares engine state over a node.
|
|
714
|
+
|
|
715
|
+
```python
|
|
716
|
+
from ttyengine import Session, net
|
|
717
|
+
|
|
718
|
+
node = net.Node('alice')
|
|
719
|
+
node.host(7777) # listen on tcp and udp port 7777
|
|
720
|
+
|
|
721
|
+
other = net.Node('bob')
|
|
722
|
+
other.connect(('127.0.0.1', 7777), 'udp') # or 'tcp', or 'auto'
|
|
723
|
+
```
|
|
724
|
+
|
|
725
|
+
- **Topology.** By default a node that hosts relays messages between the nodes connected to it (a star). `Node(mesh=True)` makes every node that joins also connect to the nodes already there, so each pair talks directly and nothing is relayed. `Node(password=...)` rejects nodes with a different password; the check is an HMAC over a per-connection nonce, so the password is never sent and a captured handshake cannot be replayed. A relayed message is only accepted from the node it claims to come from, or from the host this node joined, and `Sync` honours forwarded entities only from that host.
|
|
726
|
+
- **Transports.** TCP links use length-prefixed frames. UDP links add a handshake, reliable ordered delivery with retransmission and fragmentation for large messages, a latest-wins unreliable mode, keep-alives and round-trip timing. Everything is non-blocking and driven by `node.update()`, which `Sync.attach` calls every frame.
|
|
727
|
+
- **Messages.** `node.send(channel, data, to=None, reliable=True)` and `node.on(channel, callback)` carry any mix of `None`, `bool`, `int`, `float`, `str`, `bytes`, `list`, `tuple`, `dict` and `set`. `'@join'` and `'@leave'` report peers coming and going.
|
|
728
|
+
|
|
729
|
+
Every layer of the simulation is shared the same way, from the session down to a single variable:
|
|
730
|
+
|
|
731
|
+
```python
|
|
732
|
+
from ttyengine.net import Node, Sync
|
|
733
|
+
|
|
734
|
+
sync = Sync(node)
|
|
735
|
+
session = Session()
|
|
736
|
+
sync.share(session, 'game') # session -> worlds -> scenes -> objects -> components -> variables
|
|
737
|
+
sync.attach(session) # pump the network inside the frame loop
|
|
738
|
+
```
|
|
739
|
+
|
|
740
|
+
| Share | What travels |
|
|
741
|
+
| --- | --- |
|
|
742
|
+
| `session` | `bgcolor`, `fgcolor`, `pause`, `pausephysics`, `pauserendering` and its worlds |
|
|
743
|
+
| `world` | `layer`, `pause`, `pausephysics`, `pauserendering` and its scene |
|
|
744
|
+
| `scene` | `gravity`, `drag`, `precision`, `bouncethreshold`, `aspect`, `ambient` and its objects |
|
|
745
|
+
| `obj` | every setting of every component it has (`transform`, `physics`, `joint`, `light`, `force`, `pen`), plus plain attributes you name |
|
|
746
|
+
| `(obj, 'x', 'y')` | just those variables |
|
|
747
|
+
|
|
748
|
+
- **Roots have names.** `share(target, 'name')` must be called with the same name on every node that takes part. The cameras, terminal settings and other per-screen values are not shared unless you ask for them with `vars=`.
|
|
749
|
+
- **Choosing variables.** `vars=('transform.x', 'hp')` shares exactly those variables of the object (`'transform'` means the whole component, a bare name such as `'x'` is looked up like `obj['x']`, and names that are not settings are read as plain attributes). `vars={'obj': (...), 'scene': (...)}` applies to every layer of that kind below the root and `exclude=` removes variables the same way. `ignore(obj)` and `filter=` keep objects out of the shared scene.
|
|
750
|
+
- **Ownership.** Each entity has one owner and only the owner's changes are accepted. Roots belong to the host (`owner=net.LOCAL` or a peer id changes that), objects belong to the node that created them. `sync.transfer(obj, peer)` hands an object over, and `sync.transfer(obj, peer, vars=('physics.xvel',))` hands over single variables, so a client can steer an object the host simulates.
|
|
751
|
+
- **Replicas.** An object owned by another node is frozen: the local physics and joints skip it and the owner's values are applied instead. `Sync(replicas='live')` keeps simulating it between updates. When an owner leaves, `orphans='drop'` removes its objects, `'adopt'` gives them to the lowest remaining node id and `'keep'` leaves them in place.
|
|
752
|
+
- **Reliability.** `share(..., reliable=False)` sends variable changes as latest-wins datagrams and refreshes the full state every `Sync(resync=1.0)` seconds so lost packets heal. Creating and removing entities is always reliable. `Sync(rate=30)` limits how often changes are sent.
|
|
753
|
+
- **Unshareable values.** Values that cannot travel, such as the functions used for `light.affect` or `force.affect`, are skipped and listed in `sync.skipped`. Naming one in `vars=` raises `NetError`. Custom components join in with `net.register(MyComponent)`.
|
|
754
|
+
|
|
755
|
+
</details>
|
|
756
|
+
|
|
638
757
|
<sub>[↑ Back to top](#top)</sub>
|
|
639
758
|
|
|
640
759
|
## Examples
|
|
@@ -31,7 +31,7 @@ Build animated, interactive scenes out of text, with collisions, joints, lightin
|
|
|
31
31
|
TTY Engine draws everything as styled text and updates the terminal once per frame. Objects are assembled from small components, which are attached automatically based on the keyword arguments you pass when creating them. A box of text becomes a physics body as soon as you give it a velocity, and a light source as soon as you give it a light.
|
|
32
32
|
|
|
33
33
|
- **No dependencies.** Image decoding (PNG, JPEG, GIF, BMP, PNM; many more when ffmpeg is installed), FIGlet text, the audio mixer and the terminal and input handling are all implemented in the standard library.
|
|
34
|
-
- **Component-based objects.** `transform`, `
|
|
34
|
+
- **Component-based objects.** `transform`, `physics`, `pen`, `force`, `joint` and `light` cover position and style, collisions, drawing, area forces, linked bodies and lighting.
|
|
35
35
|
- **Rich text output.** Truecolor, transparency and fades, bundled FIGlet fonts, and image-to-text conversion.
|
|
36
36
|
- **Input and sound included.** Keyboard and mouse input with press, release and held states, plus a built-in mixer with a small synthesizer.
|
|
37
37
|
- **Simple structure.** Write a class (or just a function) with `start`, `update` and `final` methods, and hand it to `start()`.
|
|
@@ -232,17 +232,17 @@ Mouse positions are reported in terminal cells counted from the top-left. With t
|
|
|
232
232
|
|
|
233
233
|
|
|
234
234
|
|
|
235
|
-
An object starts out empty. `create()` looks at its keyword arguments, attaches the components that own them, and passes each value on. `transform`
|
|
235
|
+
An object starts out empty. `create()` looks at its keyword arguments, attaches the components that own them, and passes each value on. `transform` is always attached; the others are added the first time you use one of their settings.
|
|
236
236
|
|
|
237
237
|
| Component | Added when you pass | What it does |
|
|
238
238
|
|---|---|---|
|
|
239
|
-
| `transform` | always | Position, text, colors, opacity, rotation, flipping, shadow. |
|
|
240
|
-
| `rendering` | always | Visibility (`show`), drawing order (`z`) and whether spaces are drawn (`spaces`). |
|
|
239
|
+
| `transform` | always | Position, text, colors, opacity, rotation, flipping, shadow, visibility (`show`), drawing order (`z`) and whether spaces are drawn (`spaces`). |
|
|
241
240
|
| `physics` | `xvel`, `yvel`, `bounciness`, `gravity`, `friction`, `mass`, `phantom`, ... | Velocity, collisions, bouncing, friction and touch callbacks. |
|
|
242
241
|
| `pen` | `pen={...}` | Paints characters at a point relative to the object. Settings: `char`, `x`, `y`, `radius`, `shape`. |
|
|
243
242
|
| `force` | `force=...` or `force={...}` | Pushes other objects, optionally limited by a radius or a filter. Settings: `strength`, `affect`, `cap`, `position`, `radius`, `torque`, `shield`. |
|
|
244
|
-
| `joint` | `preset`, `joints`, `elasticity`, `kind`, ... | Links objects together as a rope, rod, spring, hinge, slider or fixed joint. |
|
|
243
|
+
| `joint` | `preset`, `joints`, `elasticity`, `kind`, `limit`, `target`, ... | Links objects together as a rope, rod, spring, hinge, slider or fixed joint. A pinned `ball` joint can also limit and motor the follower's rotation with `limit`, `target`, `gain` and `effort`. |
|
|
245
244
|
| `light` | `light=True` or `light={...}` | Turns the object into a light source. Settings: `color`, `alpha`, `radius`, `falloff`, `shadows`, `cone`, `direction`, `glow` and more. `scene.ambient` sets the base brightness. |
|
|
245
|
+
| `humanoid` | `humanoid={'parts': {...}}` | Builds a posable figure from a graph of parts, with the object as its root part. Settings: `parts`, `solid`, `physics`, `style`, `joints`, `poses`, `cycles`, `axis`, `elasticity`, `spaces`. |
|
|
246
246
|
|
|
247
247
|
Settings can be given flat, or grouped under the component's name. The two calls below are equivalent:
|
|
248
248
|
|
|
@@ -379,6 +379,7 @@ floor = scene.obj().create('#' * 40, 0, -10, dynamic=False) # immovable
|
|
|
379
379
|
| `mass` | Defaults to the number of visible characters. |
|
|
380
380
|
| `gravity` | An `(x, y)` pair that overrides the scene's gravity for this object. |
|
|
381
381
|
| `drag` | Overrides the scene's drag for this object. |
|
|
382
|
+
| `bouncethreshold` | Impact speed below which a collision does not bounce. Defaults to `scene.bouncethreshold` (`0.25`); set it to `0` to let shallow impacts bounce. When two bodies disagree, the lower value wins. |
|
|
382
383
|
|
|
383
384
|
**Reacting to contact.** Two tools cover the two common cases:
|
|
384
385
|
|
|
@@ -398,6 +399,74 @@ player.physics.ontouch(entered)
|
|
|
398
399
|
|
|
399
400
|
`ontouch(callback, when=None, once=False)` accepts a `when(other)` filter and can be limited to a single call with `once=True`.
|
|
400
401
|
|
|
402
|
+
`ontouch` fires when one body moves into another. A body that is only resting against, or pushed against by, another body does not trigger it, so use `touch`, `sides` and `grounded` for that case.
|
|
403
|
+
|
|
404
|
+
**Headings and bouncing.** `transform.forward` and `transform.bounce` use the object's `rotation` as the heading unless you pass `angle=`. Assigning the result to `rotation` also turns the sprite and its collision cells, so keep a separate heading and pass it as `angle` when the object should not rotate:
|
|
405
|
+
|
|
406
|
+
```python
|
|
407
|
+
heading = ball_heading # your own variable, in degrees
|
|
408
|
+
if ball.transform.approaching(normal, angle=heading): # True when moving into the surface
|
|
409
|
+
heading = ball.transform.bounce(normal, angle=heading)
|
|
410
|
+
heading = ball.transform.bounce(normal, angle=heading, incoming_only=True) # same check in one call
|
|
411
|
+
dx, dy = ball.transform.forward(1, angle=heading)
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
</details>
|
|
415
|
+
|
|
416
|
+
<details>
|
|
417
|
+
<summary><b>Humanoid figures</b></summary>
|
|
418
|
+
|
|
419
|
+
|
|
420
|
+
|
|
421
|
+
A `humanoid` component turns an object into the root of a jointed, posable figure. A figure is a graph of parts: every part is built from the text you give it, one part has no parent and becomes the object itself, and every other part hangs off a parent through a joint. Nothing is built in, so the same component makes people, spiders, robots or trees.
|
|
422
|
+
|
|
423
|
+
```python
|
|
424
|
+
parts = {
|
|
425
|
+
'torso': '###\n###\n###',
|
|
426
|
+
'head': {'text': 'O', 'parent': 'torso', 'at': 'top', 'joint': 'neck'},
|
|
427
|
+
'left_arm': {'text': '|\n|\n|', 'parent': 'torso', 'at': 'top_left', 'pin': 'top', 'shift': (-0.5, 0),
|
|
428
|
+
'joint': 'shoulder', 'group': 'arm'},
|
|
429
|
+
'right_arm': {'mirror': 'left_arm'},
|
|
430
|
+
'left_thigh': {'text': '|\n|\n|', 'parent': 'torso', 'at': 'bottom_left', 'pin': 'top', 'shift': (0.5, 0),
|
|
431
|
+
'joint': 'hip', 'group': 'thigh', 'density': 10},
|
|
432
|
+
'right_thigh': {'mirror': 'left_thigh', 'flip': False},
|
|
433
|
+
'left_shin': {'text': '|\n|\n|', 'parent': 'left_thigh', 'joint': 'knee', 'group': 'shin',
|
|
434
|
+
'density': 10},
|
|
435
|
+
'right_shin': {'mirror': 'left_shin', 'flip': False},
|
|
436
|
+
}
|
|
437
|
+
poses = {'arms_out': {'arm': 90}, 'crouch': {'thigh': -60, 'shin': 100}}
|
|
438
|
+
cycles = {'walk': {'left_thigh': {'amp': -32}, 'right_thigh': {'amp': 32}, 'arm': {'amp': 35}}}
|
|
439
|
+
body = scene.obj().create(None, 20, -10, humanoid={'parts': parts, 'poses': poses, 'cycles': cycles})
|
|
440
|
+
figure = body.humanoid
|
|
441
|
+
|
|
442
|
+
figure.apply_pose('arms_out') # poses and cycles are plain dicts: figure.poses, figure.cycles
|
|
443
|
+
figure.pose('arms_out') # a registered pose name works too
|
|
444
|
+
figure.pose({'left_thigh': -30}) # angles are degrees from the rest pose, clamped to joint limits
|
|
445
|
+
figure.velocity = (0.2, None) # moves every part together
|
|
446
|
+
figure.animate('walk', phase) # call each frame with a growing phase
|
|
447
|
+
figure.jump(0.6) # only while grounded
|
|
448
|
+
figure.detach('left_shin') # frees a part and everything attached to it
|
|
449
|
+
figure.ragdoll() # releases every joint; figure.ragdoll(False) stiffens them again
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
**Placement.** A part is placed by two anchors that meet at its joint: `at` is a point on the parent and `pin` is a point on the part itself. An anchor is a name (`top`, `bottom`, `left`, `right`, `center`, `top_left`, `top_right`, `bottom_left`, `bottom_right`) or an `(x, y)` pair of fractions of the part's size. `at` defaults to `bottom` and `pin` defaults to the opposite point, so a part sits against the parent on the side of its anchor. `shift=(dx, dy)` moves the joint in cells. The part is snapped to whole cells and the joint sits exactly on its `pin`.
|
|
453
|
+
|
|
454
|
+
**Mirroring.** `{'mirror': 'name'}` reflects another part across the vertical centre line of the root (or of the part named by the `axis` setting), inherits its text, `density`, `solid`, `z`, `physics`, `style`, `group` and joint, and hangs from the mirror of the source's parent unless `parent` is given. A mirrored joint has its limits and rest angle reversed, and so do the angles you pass through a group name; set `flip` to `False` to keep the same direction on both sides.
|
|
455
|
+
|
|
456
|
+
**Naming.** A pose, cycle, `style`, `get`, `set_text` or `remove_part` key is a part name or a `group`. Every part belongs to a group with its own name and to any `group` names it lists (a string or a list), and mirrored parts share the groups of their source. An exact part name sets the raw angle; a group name applies it with the sign flip of each member.
|
|
457
|
+
|
|
458
|
+
**Joints.** `joint` is a preset name from `joint.presets` or a dict of joint settings (`range`, `rest`, `elasticity`, `durability`, ...). The default is `hinge`. The `joints` setting overrides joints by group or part name.
|
|
459
|
+
|
|
460
|
+
**Ragdoll.** `figure.ragdoll(on=True, solid=None, limits=True)` turns every pose-driven joint into a free hinge that keeps its length, so the figure collapses under gravity and swings with impacts. `solid=True` forces every part to collide with the world while it is limp, while the default `None` keeps each part's own `solid` setting, and `limits=True` keeps the joint ranges. While limp, `pose` and `animate` do nothing; `ragdoll(False)` stiffens the joints in their current angles, after which `pose` works again. `figure.ragdolled` tells the current state.
|
|
461
|
+
|
|
462
|
+
**Elasticity.** The `elasticity` setting is optional and means what it means for every `joint`: unset, each joint keeps the joint default of `1`; set, it is the default for all joints of the figure, and a `joint` dict or the `joints` setting can still override it per part or group. Standing and limp figures use the same value. Values slightly above `1` soften the correction and can remove the sub-cell wobble a heavy standing figure may keep at exactly `1`, and values above about `3` make the figure sag.
|
|
463
|
+
|
|
464
|
+
**Limp figures.** A ragdoll's limbs are real rigid bodies: each limb is a ball joint pinned at its attach point with its own mass, moment of inertia and angular velocity, and the joint limits are angular impulses between the two bodies, so spin and momentum are conserved and only contacts and friction remove energy. `elasticity` sets how firmly the pins pull back together, as it does for every other joint of the figure.
|
|
465
|
+
|
|
466
|
+
**Cycles.** A cycle channel is `bias + amp * sin(phase + shift)`, or a bare number for `amp`; `rectify=True` clamps the sine to positive values. `figure.sample(cycle, phase, scale=1.0)` returns the angles and `figure.animate(cycle, phase, weight=1.0, scale=1.0)` applies them.
|
|
467
|
+
|
|
468
|
+
**Other part settings.** `text`, `parent`, `at`, `pin`, `shift`, `joint`, `mirror`, `flip`, `group`, `density` (mass per non-blank cell), `solid`, `z`, `physics`, `style` and `spaces`. `spaces` (default `False`, also a humanoid setting) makes a part's size ignore a trailing newline like the renderer does; with `spaces=True` the empty last line counts as a row, so `'█\n' * 3` is four rows tall and whatever hangs from it sits one row lower. A part's `solid` is unset by default and then follows the figure's `solid`, whose default `None` makes every part collide with the world; `solid=False` on a part keeps it from ever colliding and `solid=True` makes it always collide. The figure's `solid` can also be a bool or a list of part or group names. The parts of one figure never collide with each other. `add_part(name, spec)` and `add_parts({...})` grow a figure later.
|
|
469
|
+
|
|
401
470
|
</details>
|
|
402
471
|
|
|
403
472
|
<details>
|
|
@@ -435,6 +504,7 @@ session.style('tint', color=(255, 80, 120), bgcolor='darkblue')
|
|
|
435
504
|
- **FIGlet fonts** are bundled. `session.styler.fonts()` lists them, and `font=` accepts any name from that list.
|
|
436
505
|
- **Shapes** are available through `session.styler.shapes`: `circle`, `ellipse`, `block`, `triangle`, `diamond` and `line`.
|
|
437
506
|
- **Images** are converted to text with `session.styler.image(path, width=..., height=...)`. PNG, JPEG, GIF, BMP and PNM are decoded by the engine itself, and other formats (WebP, TIFF, TGA, ...) are decoded through ffmpeg when it is available. If you give neither `width` nor `height`, the image is `80` columns wide (or its own pixel width, if that is smaller), so the result is the same on every terminal.
|
|
507
|
+
`shades` is the string of characters from darkest to brightest, and defaults to a 256-step gradient from a space to `█`. It is plain monochrome unless you pass `color=True`, and `bgcolor=` (a name or `(r, g, b)`) fills every cell with that background and blends transparent pixels into it.
|
|
438
508
|
|
|
439
509
|
```python
|
|
440
510
|
ring = session.styler.shapes.circle(5)
|
|
@@ -601,6 +671,55 @@ The older names keep working: `termxoffset`, `termyoffset`, `termwidth` and `ter
|
|
|
601
671
|
|
|
602
672
|
</details>
|
|
603
673
|
|
|
674
|
+
<details>
|
|
675
|
+
<summary><b>Networking: UDP, TCP, servers and peer-to-peer</b></summary>
|
|
676
|
+
|
|
677
|
+
|
|
678
|
+
|
|
679
|
+
`ttyengine.net` shares a running simulation between processes over TCP, UDP or both, using only the standard library. A `Node` is one participant: it can listen (`host`), connect (`connect`) or do both, so the same code builds a dedicated server, a client, or a peer-to-peer mesh. A `Sync` shares engine state over a node.
|
|
680
|
+
|
|
681
|
+
```python
|
|
682
|
+
from ttyengine import Session, net
|
|
683
|
+
|
|
684
|
+
node = net.Node('alice')
|
|
685
|
+
node.host(7777) # listen on tcp and udp port 7777
|
|
686
|
+
|
|
687
|
+
other = net.Node('bob')
|
|
688
|
+
other.connect(('127.0.0.1', 7777), 'udp') # or 'tcp', or 'auto'
|
|
689
|
+
```
|
|
690
|
+
|
|
691
|
+
- **Topology.** By default a node that hosts relays messages between the nodes connected to it (a star). `Node(mesh=True)` makes every node that joins also connect to the nodes already there, so each pair talks directly and nothing is relayed. `Node(password=...)` rejects nodes with a different password; the check is an HMAC over a per-connection nonce, so the password is never sent and a captured handshake cannot be replayed. A relayed message is only accepted from the node it claims to come from, or from the host this node joined, and `Sync` honours forwarded entities only from that host.
|
|
692
|
+
- **Transports.** TCP links use length-prefixed frames. UDP links add a handshake, reliable ordered delivery with retransmission and fragmentation for large messages, a latest-wins unreliable mode, keep-alives and round-trip timing. Everything is non-blocking and driven by `node.update()`, which `Sync.attach` calls every frame.
|
|
693
|
+
- **Messages.** `node.send(channel, data, to=None, reliable=True)` and `node.on(channel, callback)` carry any mix of `None`, `bool`, `int`, `float`, `str`, `bytes`, `list`, `tuple`, `dict` and `set`. `'@join'` and `'@leave'` report peers coming and going.
|
|
694
|
+
|
|
695
|
+
Every layer of the simulation is shared the same way, from the session down to a single variable:
|
|
696
|
+
|
|
697
|
+
```python
|
|
698
|
+
from ttyengine.net import Node, Sync
|
|
699
|
+
|
|
700
|
+
sync = Sync(node)
|
|
701
|
+
session = Session()
|
|
702
|
+
sync.share(session, 'game') # session -> worlds -> scenes -> objects -> components -> variables
|
|
703
|
+
sync.attach(session) # pump the network inside the frame loop
|
|
704
|
+
```
|
|
705
|
+
|
|
706
|
+
| Share | What travels |
|
|
707
|
+
| --- | --- |
|
|
708
|
+
| `session` | `bgcolor`, `fgcolor`, `pause`, `pausephysics`, `pauserendering` and its worlds |
|
|
709
|
+
| `world` | `layer`, `pause`, `pausephysics`, `pauserendering` and its scene |
|
|
710
|
+
| `scene` | `gravity`, `drag`, `precision`, `bouncethreshold`, `aspect`, `ambient` and its objects |
|
|
711
|
+
| `obj` | every setting of every component it has (`transform`, `physics`, `joint`, `light`, `force`, `pen`), plus plain attributes you name |
|
|
712
|
+
| `(obj, 'x', 'y')` | just those variables |
|
|
713
|
+
|
|
714
|
+
- **Roots have names.** `share(target, 'name')` must be called with the same name on every node that takes part. The cameras, terminal settings and other per-screen values are not shared unless you ask for them with `vars=`.
|
|
715
|
+
- **Choosing variables.** `vars=('transform.x', 'hp')` shares exactly those variables of the object (`'transform'` means the whole component, a bare name such as `'x'` is looked up like `obj['x']`, and names that are not settings are read as plain attributes). `vars={'obj': (...), 'scene': (...)}` applies to every layer of that kind below the root and `exclude=` removes variables the same way. `ignore(obj)` and `filter=` keep objects out of the shared scene.
|
|
716
|
+
- **Ownership.** Each entity has one owner and only the owner's changes are accepted. Roots belong to the host (`owner=net.LOCAL` or a peer id changes that), objects belong to the node that created them. `sync.transfer(obj, peer)` hands an object over, and `sync.transfer(obj, peer, vars=('physics.xvel',))` hands over single variables, so a client can steer an object the host simulates.
|
|
717
|
+
- **Replicas.** An object owned by another node is frozen: the local physics and joints skip it and the owner's values are applied instead. `Sync(replicas='live')` keeps simulating it between updates. When an owner leaves, `orphans='drop'` removes its objects, `'adopt'` gives them to the lowest remaining node id and `'keep'` leaves them in place.
|
|
718
|
+
- **Reliability.** `share(..., reliable=False)` sends variable changes as latest-wins datagrams and refreshes the full state every `Sync(resync=1.0)` seconds so lost packets heal. Creating and removing entities is always reliable. `Sync(rate=30)` limits how often changes are sent.
|
|
719
|
+
- **Unshareable values.** Values that cannot travel, such as the functions used for `light.affect` or `force.affect`, are skipped and listed in `sync.skipped`. Naming one in `vars=` raises `NetError`. Custom components join in with `net.register(MyComponent)`.
|
|
720
|
+
|
|
721
|
+
</details>
|
|
722
|
+
|
|
604
723
|
<sub>[↑ Back to top](#top)</sub>
|
|
605
724
|
|
|
606
725
|
## Examples
|