Skip to content

docs(readme): update architecture comparison tables#81

Merged
CedaryCat merged 2 commits intomainfrom
develop
Mar 17, 2026
Merged

docs(readme): update architecture comparison tables#81
CedaryCat merged 2 commits intomainfrom
develop

Conversation

@CedaryCat
Copy link
Owner

@CedaryCat CedaryCat commented Mar 17, 2026

Summary by Sourcery

Document and clarify the tradeoffs between UnifierTSL and proxy-based multi-world architectures, and align README terminology around runtime architecture and version sourcing.

Documentation:

  • Add a detailed multi-world architecture comparison section (UnifierTSL vs proxy-based) in both English and Chinese READMEs, covering deployment, runtime coordination, and operations tradeoffs.
  • Rename the architecture section to “Runtime Architecture” and slightly refine explanatory text about future example plugins and Terraria version sourcing in the version matrix.

@sourcery-ai
Copy link

sourcery-ai bot commented Mar 17, 2026

Reviewer's Guide

Updates the English and Chinese READMEs to introduce a new multi-world architecture comparison section, rename the architecture section to clarify it as runtime architecture, slightly refine explanatory wording, and adjust the Terraria version source description in the version matrix.

Flow diagram for choosing between UnifierTSL and proxy-based architectures

flowchart TD
  Start["Designing a multi-world Terraria setup"]

  Start --> NeedCrossMachine["Need strong cross-machine / cross-container scaling and isolation?"]
  NeedCrossMachine -->|Yes| ChooseProxy["Prefer proxy-based topology"]
  NeedCrossMachine -->|No or mostly single-node| FocusSingleNode["Optimizing single-node multi-world behavior"]

  FocusSingleNode --> NeedTightConsistency["Need tight in-process consistency for routing, migration, and state transfer?"]
  NeedTightConsistency -->|Yes| ChooseUnifier["Prefer UnifierTSL single-process coordination"]
  NeedTightConsistency -->|No| PreferEcosystem["Prioritize existing plugin ecosystem with minimal adaptation?"]

  PreferEcosystem -->|Yes| ChooseProxy
  PreferEcosystem -->|No| ChooseUnifier

  ChooseUnifier --> ConsiderHybrid["Optionally place UnifierTSL behind a higher-level gateway / proxy"]
  ChooseProxy --> ConsiderHybrid
Loading

File-Level Changes

Change Details Files
Add a structured multi-world architecture comparison section contrasting UnifierTSL with proxy-based topologies.
  • Introduce a new anchored section for architecture tradeoffs/comparison in both English and Chinese READMEs.
  • Explain the term proxy-based in an introductory note.
  • Add three collapsible detail blocks covering deployment/lifecycle, runtime coordination/migration, and operations/system shape.
  • Within each block, provide comparison tables across dimensions and indicate which approach is generally a stronger fit.
docs/README.zh-cn.md
README.md
Retitle the architecture section and navigation entries to clarify that it describes runtime architecture rather than general architecture.
  • Update the table-of-contents entry labels to use the new runtime architecture wording while preserving the same anchor ID.
  • Change the corresponding section headings from Architecture to Runtime Architecture in both English and Chinese files.
docs/README.zh-cn.md
README.md
Refine explanatory wording in overview text and version matrix to be clearer and more accurate.
  • Simplify a sentence describing future heavy features and example plugins in both languages.
  • Clarify the source description for the Terraria version in the version matrix to reference the OTAPI USP package instead of project.assets.json.
docs/README.zh-cn.md
README.md

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

Copy link

@sourcery-ai sourcery-ai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 1 issue, and left some high level feedback:

  • In the final Chinese paragraph, consider adding a space between proxy-based and the following Chinese text (e.g., proxy-based 会是你的最优选择) to keep English–Chinese spacing consistent with the rest of the document.
Prompt for AI Agents
Please address the comments from this code review:

## Overall Comments
- In the final Chinese paragraph, consider adding a space between `proxy-based` and the following Chinese text (e.g., `proxy-based 会是你的最优选择`) to keep English–Chinese spacing consistent with the rest of the document.

## Individual Comments

### Comment 1
<location path="README.md" line_range="62" />
<code_context>

 From the player's side, this still behaves like a normal Terraria entry point: clients connect to one shared listener port, and `UnifiedServerCoordinator` routes each connection to the selected world inside the same process. If you push this model further, you can build more gameplay-driven setups: fully connected multi-instance world clusters, elastic worlds that load or unload region-sized shards on demand, or private worlds tuned per player for logic and resource budgets.
-These are reachable directions, even though the launcher does not currently ship them as default out-of-the-box features, and heavier implementations like these may stay out of the launcher core itself; you can still expect usable example plugins to land under `plugins/` over time.
+These are reachable directions, even though the launcher does not currently ship them as default out-of-the-box features, you can still expect usable example plugins to land under `plugins/` over time.

 ---
</code_context>
<issue_to_address>
**suggestion (typo):** Consider fixing the comma splice by splitting into two sentences or using a semicolon.

This sentence currently joins two independent clauses with only a comma, which is a comma splice. Consider either using a semicolon ("…features; you can still expect…") or splitting into two sentences ("…features. You can still expect…").

```suggestion
These are reachable directions, even though the launcher does not currently ship them as default out-of-the-box features; you can still expect usable example plugins to land under `plugins/` over time.
```
</issue_to_address>

Sourcery is free for open source - if you like our reviews please consider sharing them ✨
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.


From the player's side, this still behaves like a normal Terraria entry point: clients connect to one shared listener port, and `UnifiedServerCoordinator` routes each connection to the selected world inside the same process. If you push this model further, you can build more gameplay-driven setups: fully connected multi-instance world clusters, elastic worlds that load or unload region-sized shards on demand, or private worlds tuned per player for logic and resource budgets.
These are reachable directions, even though the launcher does not currently ship them as default out-of-the-box features, and heavier implementations like these may stay out of the launcher core itself; you can still expect usable example plugins to land under `plugins/` over time.
These are reachable directions, even though the launcher does not currently ship them as default out-of-the-box features, you can still expect usable example plugins to land under `plugins/` over time.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion (typo): Consider fixing the comma splice by splitting into two sentences or using a semicolon.

This sentence currently joins two independent clauses with only a comma, which is a comma splice. Consider either using a semicolon ("…features; you can still expect…") or splitting into two sentences ("…features. You can still expect…").

Suggested change
These are reachable directions, even though the launcher does not currently ship them as default out-of-the-box features, you can still expect usable example plugins to land under `plugins/` over time.
These are reachable directions, even though the launcher does not currently ship them as default out-of-the-box features; you can still expect usable example plugins to land under `plugins/` over time.

@CedaryCat CedaryCat merged commit 03c8c7b into main Mar 17, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant