From 70693a430a35837fa559438a198a2dc3d2b3a300 Mon Sep 17 00:00:00 2001 From: MayaTheShy Date: Sun, 9 Nov 2025 03:11:55 -0500 Subject: [PATCH] docs: update documentation structure and build scripts for clarity --- README.md | 24 ++++++------- build_and_test.sh | 62 ++++++++++++++++++++++++++++++++++ docs/DEVELOPER_GUIDE.md | 4 +-- docs/README.md | 75 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 151 insertions(+), 14 deletions(-) create mode 100644 build_and_test.sh create mode 100644 docs/README.md diff --git a/README.md b/README.md index da75715..87babc0 100644 --- a/README.md +++ b/README.md @@ -357,27 +357,27 @@ This allows you to: ### Documentation - **[README.md](README.md)** - Main documentation (you are here) -- **[DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md)** - Quick reference for developers -- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes -- **[OVERTE_AUTH.md](OVERTE_AUTH.md)** - OAuth implementation details -- **[OVERTE_ASSIGNMENT_CLIENT_TASK.md](OVERTE_ASSIGNMENT_CLIENT_TASK.md)** - Protocol implementation -- **[ENTITY_RENDERING_ENHANCEMENTS.md](ENTITY_RENDERING_ENHANCEMENTS.md)** - Rendering implementation -- **[MODELCACHE_IMPLEMENTATION.md](MODELCACHE_IMPLEMENTATION.md)** - Asset pipeline details -- **[CI_SETUP_SUMMARY.md](CI_SETUP_SUMMARY.md)** - Continuous integration setup +- **[docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)** - Quick reference for developers +- **[docs/CHANGELOG.md](docs/CHANGELOG.md)** - Version history and changes +- **[docs/OVERTE_AUTH.md](docs/OVERTE_AUTH.md)** - OAuth implementation details +- **[docs/OVERTE_ASSIGNMENT_CLIENT_TASK.md](docs/OVERTE_ASSIGNMENT_CLIENT_TASK.md)** - Protocol implementation +- **[docs/ENTITY_RENDERING_ENHANCEMENTS.md](docs/ENTITY_RENDERING_ENHANCEMENTS.md)** - Rendering implementation +- **[docs/MODELCACHE_IMPLEMENTATION.md](docs/MODELCACHE_IMPLEMENTATION.md)** - Asset pipeline details +- **[docs/CI_SETUP_SUMMARY.md](docs/CI_SETUP_SUMMARY.md)** - Continuous integration setup ### Getting Started -1. Read [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) for build/run commands -2. Check [CHANGELOG.md](CHANGELOG.md) for recent changes -3. Review protocol details in [OVERTE_ASSIGNMENT_CLIENT_TASK.md](OVERTE_ASSIGNMENT_CLIENT_TASK.md) +1. Read [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) for build/run commands +2. Check [docs/CHANGELOG.md](docs/CHANGELOG.md) for recent changes +3. Review protocol details in [docs/OVERTE_ASSIGNMENT_CLIENT_TASK.md](docs/OVERTE_ASSIGNMENT_CLIENT_TASK.md) ### Development Workflow 1. Create feature branch: `git checkout -b feature/my-feature` -2. Make changes and test locally: `./ci-test.sh` +2. Make changes and test locally: `./scripts/ci-test.sh` 3. Commit with clear messages 4. Push and create PR in Gitea 5. CI will run automated tests -See [CI_SETUP_SUMMARY.md](CI_SETUP_SUMMARY.md) for details on the CI pipeline. +See [docs/CI_SETUP_SUMMARY.md](docs/CI_SETUP_SUMMARY.md) for details on the CI pipeline. ## License diff --git a/build_and_test.sh b/build_and_test.sh new file mode 100644 index 0000000..81e29aa --- /dev/null +++ b/build_and_test.sh @@ -0,0 +1,62 @@ +#!/bin/bash#!/bin/bash + +# Backwards compatibility wrapper - scripts have moved to scripts/# Quick build and test script for Starworld + +exec "$(dirname "$0")/scripts/build_and_test.sh" "$@" + +set -e + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" + +echo "=== Starworld Build & Test Script ===" +echo + +# 1. Build the Rust bridge +echo "[1/3] Building Rust bridge..." +cd "$SCRIPT_DIR/bridge" +cargo build --release +echo "✓ Rust bridge built successfully" +echo + +# 2. Build the C++ client +echo "[2/3] Building C++ client..." +cd "$SCRIPT_DIR" +mkdir -p build +cd build +cmake .. -DCMAKE_BUILD_TYPE=Release +make -j$(nproc) +echo "✓ C++ client built successfully" +echo + +# 3. Verify the bridge library exists +echo "[3/3] Verifying build artifacts..." +BRIDGE_PATH="$SCRIPT_DIR/bridge/target/release/libstardust_bridge.so" +if [ -f "$BRIDGE_PATH" ]; then + echo "✓ Bridge library found: $BRIDGE_PATH" + ls -lh "$BRIDGE_PATH" +else + echo "✗ Bridge library not found at: $BRIDGE_PATH" + exit 1 +fi + +CLIENT_PATH="$SCRIPT_DIR/build/starworld" +if [ -f "$CLIENT_PATH" ]; then + echo "✓ Client executable found: $CLIENT_PATH" + ls -lh "$CLIENT_PATH" +else + echo "✗ Client executable not found at: $CLIENT_PATH" + exit 1 +fi + +echo +echo "=== Build Complete! ===" +echo +echo "To test with simulation mode:" +echo " export STARWORLD_SIMULATE=1" +echo " export STARWORLD_BRIDGE_PATH=$SCRIPT_DIR/bridge/target/release" +echo " $SCRIPT_DIR/build/starworld" +echo +echo "To connect to an Overte server:" +echo " export STARWORLD_BRIDGE_PATH=$SCRIPT_DIR/bridge/target/release" +echo " $SCRIPT_DIR/build/starworld ws://domain.example.com:40102" +echo diff --git a/docs/DEVELOPER_GUIDE.md b/docs/DEVELOPER_GUIDE.md index 165debb..a1a4aff 100644 --- a/docs/DEVELOPER_GUIDE.md +++ b/docs/DEVELOPER_GUIDE.md @@ -4,7 +4,7 @@ ```bash # Full clean build -./build_and_test.sh +./scripts/build_and_test.sh # Build Rust bridge only cd bridge && cargo build --release @@ -42,7 +42,7 @@ RUST_LOG=debug ./build/starworld ```bash # Run all tests -./ci-test.sh +./scripts/ci-test.sh # Run C++ tests only ./build/starworld-tests diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..8d8be2f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,75 @@ +# Starworld Documentation + +This directory contains all project documentation organized by topic. + +## Documentation Index + +### Getting Started +- **[../README.md](../README.md)** - Main project README with quick start guide +- **[DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md)** - Developer quick reference with commands and tips + +### Project Information +- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes +- **[CI_SETUP_SUMMARY.md](CI_SETUP_SUMMARY.md)** - Continuous integration setup and workflow + +### Implementation Guides +- **[OVERTE_ASSIGNMENT_CLIENT_TASK.md](OVERTE_ASSIGNMENT_CLIENT_TASK.md)** - Overte protocol implementation details +- **[OVERTE_AUTH.md](OVERTE_AUTH.md)** - OAuth 2.0 authentication implementation guide +- **[ENTITY_RENDERING_ENHANCEMENTS.md](ENTITY_RENDERING_ENHANCEMENTS.md)** - Entity rendering system +- **[MODELCACHE_IMPLEMENTATION.md](MODELCACHE_IMPLEMENTATION.md)** - Asset download and caching + +### Planning Documents +- **[CODE_CLEANUP_PLAN.md](CODE_CLEANUP_PLAN.md)** - Code organization and cleanup plans + +## Quick Links + +### For New Developers +1. Start with [../README.md](../README.md) for project overview +2. Read [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) for build/run commands +3. Check [CHANGELOG.md](CHANGELOG.md) to understand recent changes + +### For Contributors +1. Review [CI_SETUP_SUMMARY.md](CI_SETUP_SUMMARY.md) for testing workflow +2. Read relevant implementation guides for the area you're working on +3. Follow conventions described in [CODE_CLEANUP_PLAN.md](CODE_CLEANUP_PLAN.md) + +### For Protocol Work +1. Study [OVERTE_ASSIGNMENT_CLIENT_TASK.md](OVERTE_ASSIGNMENT_CLIENT_TASK.md) for protocol details +2. Review [OVERTE_AUTH.md](OVERTE_AUTH.md) if working on authentication +3. Check Overte source code references in each document + +### For Rendering Work +1. Read [ENTITY_RENDERING_ENHANCEMENTS.md](ENTITY_RENDERING_ENHANCEMENTS.md) for rendering pipeline +2. Review [MODELCACHE_IMPLEMENTATION.md](MODELCACHE_IMPLEMENTATION.md) for asset loading +3. Check the Rust bridge code in `../bridge/src/lib.rs` + +## External Resources + +### StardustXR +- Website: https://stardustxr.org +- Documentation: https://stardustxr.org/docs +- GitHub: https://github.com/StardustXR + +### Overte +- Website: https://overte.org +- Documentation: https://docs.overte.org +- GitHub: https://github.com/overte-org/overte +- Discord: https://discord.gg/overte + +## Contributing to Documentation + +When adding or updating documentation: +1. Keep documents focused on a single topic +2. Use clear, descriptive filenames +3. Include code examples where helpful +4. Update this README.md index +5. Link between related documents +6. Keep the main README.md up to date with links + +### Documentation Style +- Use Markdown format (`.md`) +- Include a clear title and overview +- Use code blocks with language tags +- Add links to external resources +- Keep line length reasonable for readability +- Use relative links for internal references