docs: Hytopia coding standards & AI PR review guidelines#13
Open
web3dev1337 wants to merge 19 commits intomasterfrom
Open
docs: Hytopia coding standards & AI PR review guidelines#13web3dev1337 wants to merge 19 commits intomasterfrom
web3dev1337 wants to merge 19 commits intomasterfrom
Conversation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Comprehensive analysis of server/src/ covering: - Boot sequence and entry points - 8 design patterns (Singleton, Manager, Registry, Observer, Controller/Strategy, Composition, Serializable, Fixed Timestep) - Event system with typed events and 3 emission scopes - Dual transport networking (WebSocket + WebTransport) - Entity/World system with physics integration - Player lifecycle and management - Module dependency graph - Error handling (3-tier severity) - Performance optimizations (IterationMap, packet caching, update thresholds) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Comprehensive analysis of client/src/ covering: - Multi-scene Three.js rendering with 6-pass post-processing pipeline - Chunk/voxel system (16x16x16 chunks, 2x2x2 batch grouping) - Web Worker architecture for geometry generation - Entity system (~1700 line Entity.ts with 7-pass per-frame update) - 22+ Manager pattern instances with Game as service locator - Dual transport networking with msgpack serialization - glTF instanced mesh rendering pipeline - Working variables pattern for GC pressure reduction - Manual matrix management throughout - Mobile support with virtual joystick Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Comprehensive analysis of protocol/ covering: - 26 packets (2 bidirectional, 6 inbound, 18 outbound) - Tuple wire format [id, data, tick?] for minimal msgpack overhead - 44 schema files with extreme property name minification - Co-located TypeScript types + JSON Schema with JSONSchemaType<T> - Custom binary framing protocol (4-byte big-endian, 32MB cap) - Load-time Ajv schema compilation via shared singleton - Schema composition via object spread (no \$ref) - Delta encoding via all-optional properties - Fail-fast duplicate packet ID detection Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Exhaustive style guide extracted from 25+ files covering: - Naming: PascalCase classes with role suffixes, camelCase methods with verb prefixes, _underscore private fields/methods, UPPER_SNAKE_CASE constants - Import/export: default exports for classes, named for enums/types, import type usage - File organization: consistent 9-section class structure - One-liner getters, named setX() methods (no property setters) - TSDoc: comprehensive on server (with Category tags), minimal on client - Error messages: ClassName.methodName(): Description format - Arrow functions for event handlers - 7 documented inconsistencies between server and client conventions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
36 findings across 40+ files analyzed: - 4 Critical: NetworkSynchronizer God Class (1561 lines, 60+ identical handlers), Client Entity (2900 lines), 70+ identical setter+emit patterns - 18 Major: RigidBody/Collider ~1750 lines each, GLTFManager 1812 lines, tickWithPlayerInput 225 lines, monkey-patching applyImpulse, event listener leaks, fatalError for validation, 60+ client TODOs - 14 Minor: as any casts, console.log leftovers, hardcoded URIs, empty catches - 14 concrete standards for new code to prevent these smells Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Overall score: 6.6/10 across 13 principles: - Strongest: LSP (8), KISS (8), YAGNI (8), Composition over Inheritance (8) - Weakest: DIP (4/10) - heavy singleton usage, no DI, no abstractions - Coupling (5/10) - fully connected singleton dependency graph - Law of Demeter (5/10) - deep chains through managers - SRP (6/10) - Entity ~1200 lines mixing physics/visuals/animations - Top recommendations: introduce interfaces + constructor injection, decompose Entity, break up long methods Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Master guidelines document for reviewing AI-generated pull requests, compiled from server architecture, client architecture, protocol layer, style conventions, code smells, and SOLID principles analyses. Includes: hard rules, naming conventions, code organization, type safety, error handling, architecture patterns, performance patterns, formatting rules, and a comprehensive PR review checklist. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Three identical patterns is enough to warrant a mapping table or generic helper. Five was too lenient. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
New sections from mega-sappy guidelines + ArkDev code analysis: - PR requirements (testing, AI review, backwards compat assessment) - Multi-layer review process (static checks, AI, human, game regression) - Backwards compatibility rules (defaults are sacred, opt-in vs automatic) - Data-driven design principles (no magic numbers, config over hardcode) - Quality gate stack (typecheck, lint, unit, perf, AI, human, manual, regression) - Extended PR review checklist with new categories Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Strip out damage/weapon/catalog examples that are specific to mega-sappy game logic, keep rules SDK-generic. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
CODING_STANDARDS.md now focuses purely on code quality (naming, types, architecture, performance). Process/governance content extracted into new CONTRIBUTING.md (PR requirements, backwards compatibility, review layers, testing expectations). Hard rules consolidated from 16 to 13. Section numbering cleaned up. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…chable Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Section 6 covers: extract method over comments, explanatory variables, parameter objects, guard clauses over nesting, and when comments are appropriate (why, not what). Checklist updated with Code Clarity category. Sections renumbered 6-13 to accommodate. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Covers server/desktop/mobile/high-player-count considerations, what to ask yourself before submitting runtime changes, and when before/after measurements are required in the PR. Checklist and PR requirements updated to include performance. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributors should list which games they tested against (SDK examples, their own game, etc.) and on what targets. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
PR should specify which games, which devices (desktop/mobile/OS), and what actions were taken in-game to exercise the change. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Layer 5 is now general AI review — bugs, logic errors, edge cases, merge readiness. Use multiple tools (Claude Code, Codex) for independent perspectives. Layer 6 is standards compliance against CODING_STANDARDS.md. Both require fresh context. Review stack renumbered to 9 layers. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
analysis-output/for referenceDocuments
CODING_STANDARDS.mdCONTRIBUTING.mdTest plan
🤖 Generated with Claude Code