From 0ecb4635d11f783e60c36805c8744e93c226cc0a Mon Sep 17 00:00:00 2001 From: loki5512344 Date: Mon, 28 Sep 2026 17:24:34 +0200 Subject: [PATCH] docs: add a real root README and rewrite the frontend one The repository had no root README at all, and frontend/README.md was still the stock Vite template. Add a bilingual (EN/RU) overview covering the mod, site, and backend plus how they connect (%link, %config save/load), replace the frontend README with the actual stack, layout, and scripts, and fix the mod README's broken DEVELOPMENT.md link to point at DEV_GUIDE.md. --- README.md | 164 +++++++++++++++++++++++++++++++++++++++++++++ frontend/README.md | 67 +++++++++++------- mod/README.md | 2 +- 3 files changed, 207 insertions(+), 26 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..a42b6ea --- /dev/null +++ b/README.md @@ -0,0 +1,164 @@ +
+ +# LoVisual + +Open-source Minecraft utility client **and** the platform around it - website, cloud config sharing, and a Rust backend. + +Developed and maintained by [loki5512344](https://github.com/loki5512344). + +![Release](https://img.shields.io/github/v/release/loki5512344/LoVisual-?style=flat-square&color=blue) +![Java](https://img.shields.io/badge/Java-25+-orange?style=flat-square&logo=openjdk&logoColor=white) +![Rust](https://img.shields.io/badge/Rust-backend-red?style=flat-square&logo=rust&logoColor=white) +![React](https://img.shields.io/badge/Frontend-React%20%2B%20Vite-61dafb?style=flat-square&logo=react&logoColor=white) +![License](https://img.shields.io/badge/license-GPLv3-blue?style=flat-square&logo=gnu&logoColor=white) + +**[⬇ Download the mod](https://github.com/loki5512344/LoVisual-/releases/latest/download/lovisual.jar)** · [Releases](https://github.com/loki5512344/LoVisual-/releases) + +[English](#english) | [Русский](#русский) + +
+ +--- + +## English + +### What is this? + +LoVisual is three things in one repository: + +| Component | What it is | Stack | +|-----------|------------|-------| +| [`mod/`](mod) | The Minecraft client itself - 60+ modules, ClickGUI, HUD editor, theme system, custom renderer | Java 25 · Fabric · OpenGL/Vulkan | +| [`frontend/`](frontend) | The website - downloads, docs, live demos of the in-game GUI, account & config pages | React 19 · Vite · TypeScript · Tailwind · bun | +| [`backend/`](backend) | The platform services - API gateway, accounts, cloud config slots with share codes | Rust · Axum · PostgreSQL · gRPC | + +The pieces talk to each other: link the mod to your platform account with `%link`, push a config +to a cloud slot with `%config save <1-4>`, and a friend imports it by code with `%config load `. + +### Mod highlights + +- **Combat / Visuals / Player / Misc** - Reach, ESP, NameTags, Chams, FullBright, Freecam, AutoTool, FakePlayer and more (see [mod README](mod/README.md) for the full list) +- **ClickGUI** on `RShift` - module browser, settings, theme editor, config profiles +- **HUD editor** - draggable and static elements: TargetHUD, ModuleList, Watermark, Keystrokes… +- **Cloud configs** - 4 slots per account, short share codes, public showcase +- **`.lvcfg` profiles** - export/import modules, HUD and themes locally, no account needed +- **Addon API** - versioned API for extending the client + +Requires Fabric Loader, Fabric API and Sodium; optional compatibility with Iris, ViaFabricPlus, +Xaero's Minimap/World Map and more. + +### Repository layout + +``` +├── mod/ Fabric client (Gradle, Java) → mod/README.md +├── frontend/ marketing + dashboard site (bun) → frontend/README.md +├── backend/ gateway, accounts-, configs-service → backend/STRUCTURE.md +├── docs/ cross-cutting docs → docs/README.md +└── ref/ reference material (not shipped) +``` + +### Development + +Mod (from `mod/`): + +```bash +./gradlew build # compile + remap jar into build/libs +./gradlew runClient # launch a dev Minecraft client +./gradlew test # unit tests +``` + +Frontend (from `frontend/`, requires bun): + +```bash +bun install +bun run dev # http://localhost:5173 +bun run test # vitest +bun run build # type-check + production bundle +``` + +Backend (from `backend/`, requires Rust + PostgreSQL): + +```bash +cargo build +cargo test +``` + +Releases are cut by pushing a `v*` tag - GitHub Actions builds the mod jar and publishes it to +[Releases](https://github.com/loki5512344/LoVisual-/releases) as both `lovisual-.jar` +and a stable `lovisual.jar` link. + +### License + +GNU General Public License v3.0. See [LICENSE](mod/LICENSE). + +--- + +## Русский + +### Что это? + +LoVisual - три проекта в одном репозитории: + +| Компонент | Что это | Стек | +|-----------|---------|------| +| [`mod/`](mod) | Сам клиент для Minecraft - 60+ модулей, ClickGUI, редактор HUD, темы, свой рендер | Java 25 · Fabric · OpenGL/Vulkan | +| [`frontend/`](frontend) | Сайт - загрузки, документация, живые демо внутриигрового GUI, страницы аккаунта и конфигов | React 19 · Vite · TypeScript · Tailwind · bun | +| [`backend/`](backend) | Сервисы платформы - API-шлюз, аккаунты, облачные слоты конфигов с кодами расшаривания | Rust · Axum · PostgreSQL · gRPC | + +Части связаны: привяжи мод к аккаунту командой `%link`, залей конфиг в облачный слот через +`%config save <1-4>`, друг заберёт его по коду командой `%config load `. + +### Возможности мода + +- **Combat / Visuals / Player / Misc** - Reach, ESP, NameTags, Chams, FullBright, Freecam, AutoTool, FakePlayer и другие (полный список - в [README мода](mod/README.md)) +- **ClickGUI** на `RShift` - браузер модулей, настройки, редактор тем и профилей +- **Редактор HUD** - перетаскиваемые и статические элементы: TargetHUD, ModuleList, Watermark, Keystrokes… +- **Облачные конфиги** - 4 слота на аккаунт, короткие коды, публичный показ +- **Профили `.lvcfg`** - локальный экспорт/импорт модулей, HUD и тем без аккаунта +- **Addon API** - версионированное API для расширения клиента + +Нужны Fabric Loader, Fabric API и Sodium; опционально - Iris, ViaFabricPlus, Xaero's Minimap/World Map и др. + +### Структура репозитория + +``` +├── mod/ клиент Fabric (Gradle, Java) → mod/README.md +├── frontend/ сайт-витрина и дашборд (bun) → frontend/README.md +├── backend/ gateway, accounts-, configs-service → backend/STRUCTURE.md +├── docs/ сквозная документация → docs/README.md +└── ref/ референсы (не поставляется) +``` + +### Разработка + +Мод (из `mod/`): + +```bash +./gradlew build # сборка и remap jar в build/libs +./gradlew runClient # запуск dev-клиента Minecraft +./gradlew test # модульные тесты +``` + +Фронтенд (из `frontend/`, нужен bun): + +```bash +bun install +bun run dev # http://localhost:5173 +bun run test # vitest +bun run build # типы + production-сборка +``` + +Бэкенд (из `backend/`, нужны Rust и PostgreSQL): + +```bash +cargo build +cargo test +``` + +Релизы создаются пушем тега `v*` - GitHub Actions собирает jar мода и публикует в +[Releases](https://github.com/loki5512344/LoVisual-/releases) как `lovisual-<версия>.jar` +и по стабильной ссылке `lovisual.jar`. + +### Лицензия + +GNU General Public License v3.0. См. [LICENSE](mod/LICENSE). diff --git a/frontend/README.md b/frontend/README.md index d6af7e3..0c47ecb 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,32 +1,49 @@ -# React + TypeScript + Vite +# LoVisual Website -This template provides a minimal setup to get React working in Vite with HMR and some Oxlint rules. +The frontend for [LoVisual](../README.md) - a marketing site with a live in-game GUI demo, +download page, documentation, themes/showcase pages, and an account dashboard with a cloud +config manager. UI is fully bilingual (Russian default, English toggle, persisted in the URL). -Currently, two official plugins are available: +## Stack -- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs) -- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) +- **React 19 + TypeScript + Vite**, package manager: **bun** +- **Tailwind CSS v4** with custom design tokens (radii, glass panels, control sizing) +- **TanStack Query** for backend calls, **react-router** for pages +- **react-i18next** - `ru`/`en` resources per feature, compile-time key parity via `satisfies` +- **motion/react** for animation, **vitest + Testing Library** for tests +- **oxlint** for linting -## React Compiler +## Layout -The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation). - -## Expanding the Oxlint configuration - -If you are developing a production application, we recommend enabling type-aware lint rules by installing `oxlint-tsgolint` and editing `.oxlintrc.json`: - -```json -{ - "$schema": "./node_modules/oxlint/configuration_schema.json", - "plugins": ["react", "typescript", "oxc"], - "options": { - "typeAware": true - }, - "rules": { - "react/rules-of-hooks": "error", - "react/only-export-components": ["warn", { "allowConstantExport": true }] - } -} +``` +src/ +├── app/ router, providers, App shell +├── features/ one folder per domain (account, cloud, demo, themes, ...) +│ └── / api.ts · i18n/{ru,en}.ts · components/ · tests/ +├── pages/ route-level pages composing features +├── shared/ ui primitives, i18n bootstrap, easter eggs, helpers +└── test/ vitest setup and utilities ``` -See the [Oxlint rules documentation](https://oxc.rs/docs/guide/usage/linter/rules) for the full list of rules and categories. +Feature-folder rules: API calls, translations and components live together; no cross-feature +imports except through `shared/`. + +## Scripts + +```bash +bun install # install dependencies +bun run dev # dev server on http://localhost:5173 (proxies /api to the backend) +bun run test # vitest run +bun run build # tsc -b + vite build → dist/ +bun run lint # oxlint +bun run gen:themes # regenerate theme tokens from the mod palette (scripts/extract-themes.ts) +``` + +The dev server expects the Rust gateway on `127.0.0.1:8080` (see [`backend/`](../backend)); +without it, API-backed pages degrade to demo/offline states by design. + +## Testing + +Unit and component tests are colocated in `features/*/tests/` and `shared/**/tests/`; +run a single file with `bunx vitest run src/features/account/tests/account.test.tsx`. +Translation parity (ru ↔ en key sets) is enforced at compile time and in tests. diff --git a/mod/README.md b/mod/README.md index 93964f2..6c6e8d9 100644 --- a/mod/README.md +++ b/mod/README.md @@ -135,7 +135,7 @@ LoVisual разрабатывается и поддерживается [loki551 ### Docs -- [Development guide](DEVELOPMENT.md) — project rules, how to add modules/HUD/events/config +- [Development guide](DEV_GUIDE.md) — project rules, how to add modules/HUD/events/config ### License