ClansQOL — Educational Combat-Automation Research Harness

ClansQOL is a source-available educational research project for studying event-driven control systems, client instrumentation, state machines, rendering hooks, compatibility boundaries, and safety controls in a Minecraft 1.8.9 test environment. It is preserved as a technical case study, not marketed or presented as a product, competitive tool, or approved multiplayer modification.

Caution

Research use only. Do not use this project on Mineplex or another public multiplayer server. ClansQOL is independent and is not affiliated with, endorsed by, or approved by Mineplex, Mojang, or Microsoft. Its experiments include automated input, targeting assistance, packet interception, and additional visual information. Those behaviors may violate server rules or terms and can result in suspension or a permanent ban. Nothing in this repository is represented as undetectable, permitted, safe, or suitable for competitive play. Use only in a local, private, or otherwise explicitly authorized test environment.

Research purpose

The repository documents several engineering questions:

• How can packet, tick, input, render, and world events be normalized behind a testable bridge?
• How can deterministic state machines model timing-sensitive behavior without blocking a client thread?
• How can target-selection and movement-prediction decisions be evaluated against synthetic fixtures?
• How can a launcher validate an exact client fingerprint before attaching an instrumentation agent?
• How can signed mapping profiles, detached signatures, and edition boundaries reduce accidental execution in unsupported environments?
• How can automated systems expose conservative defaults, explicit status, and reproducible tests?

The historical module names—AutoEvade, AntiEvade, Aim Assist, AutoBow, AutoClicker, AutoBottle, AutoSoup, AntiIllusion, AntiDebuff, Smoke Ghost, Nametags, and Item ESP—identify experiments in the source and test suite. Their presence is documentation of the studied behaviors, not a recommendation to deploy them on a server.

Responsible-use boundary

• Work with synthetic fixtures, local worlds, private test servers, or environments whose owner has given explicit permission.
• Do not use the code to gain an advantage over other players or to evade moderation or anti-cheat systems.
• Do not describe a build as safe, allowed, undetectable, or endorsed.
• Do not request or provide help deploying it to Mineplex or another public server.
• Treat the included executables as archived research artifacts. Source review and isolated testing are preferred.
• You are responsible for the rules, terms, laws, and consequences that apply to your use.

See RESEARCH_USE.md for the project’s full research and safety statement.

Study configurations

Two compile-time configurations exist so their trust boundaries can be compared:

Offline research build

• Contains the local runtime and has no account, activation, entitlement, heartbeat, remote-diagnostics, or backend dependency.
• Can be studied with networking blocked.
• Is intended for isolated reproduction and code-path analysis.

Access-controlled research build

• Preserves the historical signed-access and protected-runtime architecture for security analysis.
• Requires an operator-provided CLANSQOL_LICENSE_URL; no service URL or private credential is embedded.
• Exists to document and test the access boundary, not to advertise a commercial service.

Both configurations use the same experimental control, UI, mapping, and adapter sources. Their differences are limited to access delivery and remote-diagnostics wiring.

Repository layout

• runtime/ — experimental module logic, UI, Forge adapter, fixtures, and compile-time edition wiring.
• injector/ — launcher, Attach API helper, Java agent, signed mapping profiles, native decision component, and tests.
• scripts/ — reproducible build and edition-boundary checks.
• RELEASE.md — artifact provenance, verification, and responsible handling.

Reproduce a build

Building is documented for code review, reproducibility, and authorized laboratory testing:

.\scripts\Build-ClansQOLEdition.ps1 `
  -Edition Offline `
  -Version 4.34.1 `
  -Jdk8Home C:\path\to\jdk8 `
  -AttachJdkHome C:\path\to\jdk21

Use -Edition Keyed only when studying the access-controlled boundary with infrastructure you own. The build writes artifacts and SHA-256 checksums to release\<version>\<edition>.

Project status

This repository is maintained as an educational archive and engineering reference. It has no storefront, paid access offer, public-server support, or claim of competitive legitimacy. Technical issue reports should be limited to reproducibility, testing, documentation, safety, and defensive analysis.