docs: add site (#592)

Author: andrewgazelka

.github/workflows/deploy.yml

@@ -0,0 +1,50 @@
+name: Deploy VitePress site to Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Install dependencies
+        run: npm ci
+      - name: Build with VitePress
+        run: npm run docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,4 +1,6 @@
 /.vscode
+node_modules/
+docs/.vitepress/cache
 /target
 .env
 *.webm

Cargo.lock

@@ -25,7 +25,7 @@ members = [
   'crates/hyperion-stats',
   'crates/hyperion-text',
   'crates/hyperion-utils',
-  'events/proof-of-concept',
+  'events/tag',
   'crates/hyperion-permission',
   'crates/hyperion-clap',
   'crates/hyperion-command',

Cargo.toml

@@ -25,7 +25,6 @@ pub struct BroadcastGlobal<'a> {
 }
 
 #[derive(Archive, Deserialize, Serialize, Clone, PartialEq)]
-// #[rkyv(derive(Debug))]
 pub struct BroadcastLocal<'a> {
     pub center: ChunkPosition,
     pub exclude: u64,
@@ -36,7 +35,6 @@ pub struct BroadcastLocal<'a> {
 }
 
 #[derive(Archive, Deserialize, Serialize, Clone, PartialEq)]
-// #[rkyv(derive(Debug))]
 pub struct Unicast<'a> {
     pub stream: u64,
     pub order: u32,
@@ -50,7 +48,6 @@ pub struct Unicast<'a> {
 pub struct Flush;
 
 #[derive(Archive, Deserialize, Serialize, Clone, PartialEq)]
-// #[rkyv(derive(Debug))]
 pub enum ServerToProxyMessage<'a> {
     UpdatePlayerChunkPositions(UpdatePlayerChunkPositions),
     BroadcastGlobal(BroadcastGlobal<'a>),

crates/hyperion-proto/src/server_to_proxy.rs

@@ -0,0 +1,96 @@
+# Hyperion Minecraft Engine
+
+## Overview
+
+Hyperion is a custom Minecraft game engine designed for building scalable, high-performance game modes and events.
+Unlike traditional Minecraft server implementations, Hyperion takes a ground-up approach to game mechanics through its
+plugin-first architecture.
+
+## Key Features
+
+### Plugin-First Architecture
+
+Hyperion starts with minimal base features and implements game mechanics through a fundamental plugin system. This
+approach differs from traditional Minecraft servers that modify vanilla implementations:
+
+- Core mechanics like combat are implemented as plugins
+- Easily swap between different combat systems (e.g., 1.8 vs modern combat)
+- Flexible customization without complex patching of vanilla code
+
+### Entity Component System (ECS)
+
+Hyperion utilizes [Flecs](https://github.com/SanderMertens/flecs), an Entity Component System, as its core architecture:
+
+- Entities are organized in a table-like structure
+    - Rows represent individual entities
+    - Columns represent components (e.g., health, position)
+- Systems process entities through efficient iterations
+- Components can be dynamically added (e.g., LastAttacked component for combat)
+- For a more accurate representation of an ECS, see the [ECS FAQ](https://github.com/SanderMertens/ecs-faq)
+
+### Performance Optimization
+
+#### Parallel Processing
+
+The ECS architecture enables efficient parallel processing:
+
+- Entities are automatically partitioned across available threads
+- Systems can process multiple entities simultaneously
+- Automatic handling of dependencies and thread safety
+- Optimal resource utilization while maintaining data consistency
+
+:green{hola} oi
+
+#### Proxy Layer
+
+Performance bottlenecks are addressed through a sophisticated proxy system:
+
+- Horizontally scaled proxy layer
+- Vertically scaled game server
+- Efficient packet broadcasting:
+    - Global broadcast capabilities
+    - Regional broadcasting for proximity-based updates
+    - Optimized movement packet distribution
+
+### Scalability
+
+Hyperion is designed to handle large-scale events efficiently:
+
+- Support for up > 10,000 concurrent players
+- Performance constraints:
+    - 20 ticks per second (50ms per tick)
+    - Optimized processing within timing constraints
+- Visibility optimization:
+    - Configurable player render limits (400-700 players)
+    - Customizable nametag visibility
+    - Moderator-specific viewing options
+
+## Technical Considerations
+
+### Performance Management
+
+- FPS optimization through selective rendering
+- Nametag rendering management for performance
+- Regional packet distribution to reduce network load
+- Modular performance settings for different user roles
+
+### Resource Utilization
+
+- 50ms processing window per tick
+- Balanced distribution of computational resources
+- Efficient handling of IO operations through proxy layer
+- Optimized packet management for large player counts
+
+## Use Cases
+
+Hyperion is ideal for creating custom Minecraft experiences similar to popular servers like Hypixel or Mineplex, where
+vanilla mechanics can be completely customized to create unique game modes and events.
+
+## Getting Started
+
+Developers interested in using Hyperion should familiarize themselves with:
+
+- Entity Component Systems (particularly Flecs)
+- Minecraft networking protocols
+- Parallel processing concepts
+- Plugin development principles

docs/.vitepress/benchmarks.md

@@ -0,0 +1,33 @@
+import {defineConfig} from 'vitepress'
+
+import {withMermaid} from 'vitepress-plugin-mermaid';
+
+
+// https://vitepress.dev/reference/site-config
+const config = defineConfig({
+    title: "Hyperion",
+    description: "The most advanced Minecraft game engine built in Rust",
+    themeConfig: {
+        // https://vitepress.dev/reference/default-theme-config
+        nav: [
+            {text: 'Home', link: '/'},
+            {text: 'Guide', link: '/guide'},
+        ],
+
+        sidebar: [
+            {
+                text: 'Guide',
+                items: [
+                    {text: 'Introduction', link: '/guide/introduction'},
+                    {text: 'Architecture', link: '/guide/architecture'},
+                ]
+            }
+        ],
+        socialLinks: [
+            {icon: 'github', link: 'https://github.com/vuejs/vitepress'}
+        ]
+    }
+})
+
+
+export default withMermaid(config);

docs/.vitepress/config.mts

@@ -0,0 +1,56 @@
+<script setup>
+import { computed, defineProps } from 'vue'
+
+const props = defineProps({
+  target: {
+    type: String,
+    required: true
+  },
+  style: {
+    type: String,
+    default: 'atom-one-dark'
+  },
+  height: {
+    type: String,
+    default: '434px'
+  }
+})
+
+const iframeUrl = computed(() => {
+  const params = new URLSearchParams({
+    target: props.target,
+    style: props.style,
+    type: 'code',
+    showBorder: 'on',
+    showLineNumbers: 'on',
+    showFileMeta: 'on',
+    showFullPath: 'on',
+    showCopy: 'on'
+  })
+  return `https://emgithub.com/iframe.html?${params.toString()}`
+})
+</script>
+
+<template>
+  <iframe
+      :src="iframeUrl"
+      frameborder="0"
+      scrolling="no"
+      :style="{ width: '100%', height }"
+      allow="clipboard-write"
+      class="github-snippet"
+  ></iframe>
+</template>
+
+<style scoped>
+.github-snippet {
+  padding:  -100px -100px -100px 0;
+  border-radius: 8px;
+}
+
+@media (max-width: 640px) {
+  .github-snippet {
+    margin: 12px -16px;
+  }
+}
+</style>

docs/.vitepress/theme/components/GithubSnippet.vue

@@ -0,0 +1,4 @@
+/* .vitepress/theme/custom.css */
+.green-tps {
+    color: #4ade80; /* You can change this to any green color you prefer */
+}

docs/.vitepress/theme/custom.css

@@ -0,0 +1,17 @@
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme'
+
+import GithubSnippet from './components/GithubSnippet.vue'
+import './custom.css'
+
+// import {NolebaseInlineLinkPreviewPlugin} from '@nolebase/vitepress-plugin-inline-link-preview/client';
+
+
+// export default DefaultTheme
+
+export default {
+    ...DefaultTheme,
+    enhanceApp({app}) {
+        app.component('GithubSnippet', GithubSnippet)
+    }
+};