Version 1.0: Initial Release

.gitignore

@@ -1 +1,11 @@
-.idea
+.idea
+*.iml
+target
+dependency-reduced-pom.xml
+# Live config holds MySQL credentials - never commit a populated one.
+# The shipped template lives at src/main/resources/config.yml.
+/config.yml
+
+# Python
+__pycache__/
+*.pyc

README.md

@@ -1,2 +1,84 @@
 # BlockVault
-BlockVault is a collaborative Minecraft plugin where players work together to collect every block in the game and display them.
+
+![img](https://i.imgur.com/DPcMoaq.png)
+
+BlockVault drives a purpose-built museum for a twelve-month, server-wide block
+collection event. Players donate one of every obtainable block in Minecraft
+Java **26.2**; each donation is consumed and recorded, a donor head appears on
+the shelf, and six themed floors unlock over the season.
+
+## Requirements
+
+| | |
+|---|---|
+| Minecraft | Java Edition **26.2** (`api-version '26.2'`) |
+| Server | Paper |
+| Build JDK | **25** (paper-api 26.2 ships Java 25 bytecode) |
+| Database | MySQL 8.0+ / MariaDB 10.5+ |
+| Package | `dev.anchorlight.blockvault` |
+
+HikariCP and the MySQL driver are pulled at runtime via `libraries:` in
+`plugin.yml` — no shading.
+
+## Setup
+
+1. **Apply the schema.** Run `src/main/resources/blockvault_schema.sql` against
+   your database before first start.
+2. **Generate the data artefacts** from section 12 of the implementation brief:
+   ```
+   python tools/gen_artifacts.py       # reads tools/target_list.txt
+   ```
+   This produces `src/main/resources/vault_items.yml`,
+   `src/main/resources/vault_slots.json` and `tools/spawn_frames.mcfunction`.
+   The plugin **disables itself** if `vault_slots.json` is missing — it never
+   regenerates the target list.
+3. **Paste the schematic** `sky_vault.schem` at the world origin, then run
+   `spawn_frames.mcfunction` standing on that origin to spawn the empty frames.
+4. **Configure** `config.yml` (git-ignored — holds DB credentials):
+   database connection, the world `origin:` the schematic sits at, the chapter
+   `opens-at` dates, and optionally a `discord.webhook-url`.
+5. Start the server. Bootstrap seeds `bv_target` / `bv_chapter` from the manifest
+   and runs a three-way validation pass (manifest ↔ `vault_items.yml` ↔
+   `bv_target`) plus new-block detection.
+6. `/bvstart` opens the event.
+
+## How it works
+
+- **Submissions are transactional.** Order is always write → confirm commit →
+  consume the item. If the database is unreachable the block stays in the
+  player's hand. `bv_submission.material` is the primary key, so one-of-each is
+  enforced by the database and simultaneous submits race safely.
+- **The head is the state indicator.** No separate colour-glass state block.
+  `/bvupdatestate` reconciles the world against the database and only ever writes
+  the manifest `head` cells — never structure — in a single summary line.
+- **Chapters** open on their scheduled date *or* at 90% of the previous chapter,
+  whichever comes first. Earlier chapters never close. Unlock breaks one
+  `iron_bars` seal and runs a broadcast/title/fireworks/BossBar ceremony.
+- **The target list is frozen per `edition`.** New blocks go in as a new edition,
+  never the running one.
+- **Chapter advancements** ship as a bundled datapack, written into
+  `<world>/datapacks/blockvault/` on load and granted by the plugin when a
+  chapter reaches 100%. A world reload may be needed the first time.
+
+## Commands
+
+| Command | Permission | Purpose |
+|---|---|---|
+| `/bvsubmit` | `blockvault.submit` | Donate the held block (in-region, no creative) |
+| `/bvprogress` | `blockvault.progress` | Current-chapter bar + overall bar |
+| `/bvleaderboard [month]` | `blockvault.leaderboard` | Top 10 all-time, or this month |
+| `/bvfind <block>` | `blockvault.find` | Level, room, shelf coordinates |
+| `/bvinfo <block>` | `blockvault.info` | Rarity, points, chapter, status |
+| `/bvmissing [chapter] [page]` | `blockvault.missing` | Outstanding list, paginated |
+| `/bvcheck` | `blockvault.check` | What in your inventory the vault needs |
+| `/bvme` | `blockvault.me` | Your blocks, points, rank |
+| `/bvhistory <block>` | `blockvault.history` | Who donated it and when |
+| `/bvedition` | `blockvault.edition` | Frozen target-list version |
+| `/bvstart [stop]` | `blockvault.start` | Open / close the event |
+| `/bvupdatestate` | `blockvault.updatestate` | Reconcile world ↔ database (console-safe) |
+| `/bvreload` | `blockvault.reload` | Reload config without restart |
+| `/bvrevoke <block>` | `blockvault.revoke` | Reverse a submission, refund points, remove head |
+| `/bvrepair` | `blockvault.repair` | Rebuild missing frames and heads from the manifest |
+| `/bvbackup` | `blockvault.backup` | Timestamped `mysqldump` |
+
+`blockvault.build` bypasses in-region build/interaction protection.

pom.xml

@@ -4,15 +4,16 @@
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
 
-  <groupId>me.benrobson</groupId>
+  <groupId>dev.anchorlight</groupId>
   <artifactId>blockvault</artifactId>
   <version>1.0.0</version>
   <packaging>jar</packaging>
 
   <name>blockvault</name>
 
   <properties>
-    <java.version>21</java.version>
+    <java.version>25</java.version>
+    <maven.compiler.release>25</maven.compiler.release>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
   </properties>
 
@@ -23,49 +24,51 @@
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-compiler-plugin</artifactId>
         <version>3.13.0</version>
-        <configuration>
-          <source>${java.version}</source>
-          <target>${java.version}</target>
-        </configuration>
-      </plugin>
-      <plugin>
-        <groupId>org.apache.maven.plugins</groupId>
-        <artifactId>maven-shade-plugin</artifactId>
-        <version>3.5.3</version>
-        <executions>
-          <execution>
-            <phase>package</phase>
-            <goals>
-              <goal>shade</goal>
-            </goals>
-          </execution>
-        </executions>
       </plugin>
     </plugins>
     <resources>
       <resource>
         <directory>src/main/resources</directory>
         <filtering>true</filtering>
+        <excludes>
+          <exclude>datapack/**</exclude>
+        </excludes>
+      </resource>
+      <resource>
+        <directory>src/main/resources</directory>
+        <filtering>false</filtering>
+        <includes>
+          <include>datapack/**</include>
+        </includes>
       </resource>
     </resources>
   </build>
 
   <repositories>
-      <repository>
-        <id>papermc-repo</id>
-        <url>https://repo.papermc.io/repository/maven-public/</url>
-      </repository>
     <repository>
-      <id>sonatype</id>
-      <url>https://oss.sonatype.org/content/groups/public/</url>
+      <id>papermc-repo</id>
+      <url>https://repo.papermc.io/repository/maven-public/</url>
     </repository>
   </repositories>
 
   <dependencies>
     <dependency>
       <groupId>io.papermc.paper</groupId>
       <artifactId>paper-api</artifactId>
-      <version>1.21.3-R0.1-SNAPSHOT</version>
+      <version>[26.2.build,)</version>
+      <scope>provided</scope>
+    </dependency>
+    <!-- Supplied at runtime via plugin.yml `libraries:` - compile-only here. -->
+    <dependency>
+      <groupId>com.zaxxer</groupId>
+      <artifactId>HikariCP</artifactId>
+      <version>5.1.0</version>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>com.mysql</groupId>
+      <artifactId>mysql-connector-j</artifactId>
+      <version>8.4.0</version>
       <scope>provided</scope>
     </dependency>
   </dependencies>