construct-tcp-examples

Example integration harness for the Construct TCP simulation API.

Apache-2.0 Go clients that connect to a Construct TCP host on 127.0.0.1:17000, spawn rigid-body constructs, and drive the simulation over JSON. This repo is the public home of the old construct_tests numbered examples (test1 … test13, plus load test 14).

Default: example 13 — spawns a showcase of every supported part shape on the planet surface.

Video demo: SoulGlitch showcase — all 13 tests + planet walk (YouTube)

License: Apache-2.0 (see LICENSE).

Quick start

1. Start a Construct TCP host

You need a server listening on 127.0.0.1:17000 (Construct TCP / PrimeCraft wire format). Point your host at the multiverse scenario if you want planet queries (example 6) and surface-relative spawns (example 13).

2. Run an example

git clone https://github.com/openfluke/construct-tcp-examples.git
cd construct-tcp-examples
go run .            # same as go run . 13
go run . 13         # shape showcase (default)
go run . -h         # all example numbers

Run the whole module (go run . N). Do not go run test13.go alone — types live in shared.go.

Example 13 (default)

go run . 13 — Rons Gone Wrong: shape showcase.

1. Connects to :17000
2. query_state — reads planet center, radius, player position
3. Spawns clusters of box, sphere, capsule, cylinder parts just above the surface (anchored to live server state, not hard-coded world origin)
4. Leaves constructs simulating until you Ctrl+C

This is the best “hello world” for create_construct with real planet context. See docs/test13-shape-showcase.md.

All examples

Protocol

Transport

• Address: 127.0.0.1:17000 (ConstructServerAddress in shared.go)
• Client → server: 4-byte little-endian length + UTF-8 JSON
• Server → client: raw JSON (query_performance may be length-prefixed)

Compatible with PrimeCraft ConstructServer.cs framing.

Common messages

Part types: box, sphere, capsule, cylinder.

Minimal create

conn, _ := net.Dial("tcp", "127.0.0.1:17000")
req := map[string]any{
    "type":         "create_construct",
    "construct_id": "hello",
    "parts": []map[string]any{{
        "id": "box1", "type": "box",
        "size": []float32{1, 1, 1},
        "pos":  []float32{0, 4, 0},
        "color": []float32{1, 0, 0},
    }},
}
body, _ := json.Marshal(req)
writePacket(conn, body) // shared.go

Dependencies

go mod download
go run . 13

Examples 1–9, 12–13 have no loom dependency.

Layout

construct-tcp-examples/
  main.go           go run . [n]  — default 13
  shared.go         protocol + writePacket
  test1.go … test13.go
  loadtesting.go    example 14
  poly_adapter.go         type aliases → internal/adapter
  internal/adapter/       loom CPU-MC network wrapper
  test/                   go test ./test/...
  docs/             Per-example notes (test1–test13)

Contributing

Keep historical testN.go names. New example: add file, register in main.go, document in this README.