Skip to content

Commit f4dcff0

Browse files
wjddusrb03claude
wjddusrb03
and
claude
committed
Add documentation (20 pages) and PlaceholderAPI utility
- docs/ folder with complete API documentation (20 pages) - Installation, Quick Start, all feature guides - API Reference, Easing Functions, Admin Commands - PlaceholderUtil for safe PlaceholderAPI integration - PlaceholderAPI detection log on startup Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 7a64ac6 commit f4dcff0

20 files changed

Lines changed: 1527 additions & 0 deletions

‎docs/API-Reference.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# API Reference
2+
3+
## Entry Point: `DisplayAPI`
4+
5+
All API access starts from the static `DisplayAPI` class.
6+
7+
### Factory Methods
8+
9+
```java
10+
DisplayAPI.text(Location) → TextDisplayBuilder
11+
DisplayAPI.block(Location) → BlockDisplayBuilder
12+
DisplayAPI.item(Location) → ItemDisplayBuilder
13+
DisplayAPI.popup(Location) → PopupBuilder
14+
DisplayAPI.interactive(Location) → InteractiveBuilder
15+
DisplayAPI.animate(SpawnedDisplay) → AnimationBuilder
16+
DisplayAPI.follow(SpawnedDisplay, Entity) → FollowDisplay
17+
DisplayAPI.leaderboard(Location) → Leaderboard
18+
DisplayAPI.group(String id, Location) → DisplayGroup
19+
```
20+
21+
### Management
22+
23+
```java
24+
DisplayAPI.getById(String id) → SpawnedDisplay
25+
DisplayAPI.remove(String id) → void
26+
DisplayAPI.removeAll() → void
27+
DisplayAPI.getManager() → DisplayManager
28+
DisplayAPI.getPersistenceManager() → PersistenceManager
29+
DisplayAPI.getPlugin() → Plugin
30+
DisplayAPI.getDefaultViewRange() → float
31+
```
32+
33+
## Class Overview
34+
35+
### Builders (`com.wjddusrb03.displayapi.builder`)
36+
37+
| Class | Description |
38+
|-------|-------------|
39+
| `AbstractDisplayBuilder<T>` | Base builder with common properties |
40+
| `TextDisplayBuilder` | Text hologram builder |
41+
| `BlockDisplayBuilder` | Block display builder |
42+
| `ItemDisplayBuilder` | Item display builder |
43+
| `PopupBuilder` | Animated popup builder |
44+
| `InteractiveBuilder` | Clickable display builder |
45+
46+
### Display (`com.wjddusrb03.displayapi.display`)
47+
48+
| Class | Description |
49+
|-------|-------------|
50+
| `SpawnedDisplay` | Wrapper around a spawned Display entity |
51+
| `DisplayGroup` | Groups multiple displays |
52+
| `InteractiveDisplay` | Display + Interaction entity pair |
53+
| `FollowDisplay` | Display that follows an entity |
54+
| `Leaderboard` | Auto-updating ranked display |
55+
56+
### Animation (`com.wjddusrb03.displayapi.animation`)
57+
58+
| Class | Description |
59+
|-------|-------------|
60+
| `AnimationBuilder` | Builder for animations (presets + custom) |
61+
| `DisplayAnimation` | Running animation controller |
62+
| `Keyframe` | Single animation keyframe |
63+
| `Easing` | 12 easing function enum |
64+
65+
### Manager (`com.wjddusrb03.displayapi.manager`)
66+
67+
| Class | Description |
68+
|-------|-------------|
69+
| `DisplayManager` | Tracks all active displays, groups, interactives |
70+
| `PersistenceManager` | YAML save/load for persistent displays |
71+
72+
### Utility (`com.wjddusrb03.displayapi.util`)
73+
74+
| Class | Description |
75+
|-------|-------------|
76+
| `PlaceholderUtil` | Safe PlaceholderAPI integration |
77+
78+
### Listener (`com.wjddusrb03.displayapi.listener`)
79+
80+
| Class | Description |
81+
|-------|-------------|
82+
| `DisplayListener` | Per-player visibility on join |
83+
| `InteractionListener` | Routes click events to InteractiveDisplay |
84+
85+
## Package Structure
86+
87+
```
88+
com.wjddusrb03.displayapi
89+
├── DisplayAPI.java (static entry point)
90+
├── DisplayAPIPlugin.java (plugin main class)
91+
├── builder/
92+
│ ├── AbstractDisplayBuilder (base builder)
93+
│ ├── TextDisplayBuilder
94+
│ ├── BlockDisplayBuilder
95+
│ ├── ItemDisplayBuilder
96+
│ ├── PopupBuilder
97+
│ └── InteractiveBuilder
98+
├── display/
99+
│ ├── SpawnedDisplay (spawned entity wrapper)
100+
│ ├── DisplayGroup (group management)
101+
│ ├── InteractiveDisplay (click detection)
102+
│ ├── FollowDisplay (entity tracking)
103+
│ └── Leaderboard (ranked display)
104+
├── animation/
105+
│ ├── AnimationBuilder (animation factory)
106+
│ ├── DisplayAnimation (animation runner)
107+
│ ├── Keyframe (animation data)
108+
│ └── Easing (12 easing curves)
109+
├── manager/
110+
│ ├── DisplayManager (display tracking)
111+
│ └── PersistenceManager (YAML persistence)
112+
├── listener/
113+
│ ├── DisplayListener (visibility events)
114+
│ └── InteractionListener (click events)
115+
├── util/
116+
│ └── PlaceholderUtil (PlaceholderAPI)
117+
└── command/
118+
└── DisplayAPICommand (admin commands)
119+
```

‎docs/Admin-Commands.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Admin Commands
2+
3+
All commands require `displayapi.admin` permission (default: op).
4+
5+
## Commands
6+
7+
| Command | Alias | Description |
8+
|---------|-------|-------------|
9+
| `/displayapi test <type>` | `/dapi test <type>` | Spawn a test display |
10+
| `/displayapi list` | `/dapi list` | List all active displays and groups |
11+
| `/displayapi remove <id>` | `/dapi remove <id>` | Remove a display or group by ID |
12+
| `/displayapi removeall` | `/dapi removeall` | Remove all displays and groups |
13+
| `/displayapi save` | `/dapi save` | Save persistent displays to file |
14+
| `/displayapi reload` | `/dapi reload` | Reload config.yml |
15+
| `/displayapi info` | `/dapi info` | Show plugin version and stats |
16+
17+
## Test Types
18+
19+
`/dapi test <type>` supports these types:
20+
21+
| Type | Description |
22+
|------|-------------|
23+
| `text` | Simple text hologram |
24+
| `block` | Block display (diamond block) |
25+
| `item` | Item display (diamond sword) |
26+
| `popup` | Animated popup text |
27+
| `group` | Display group (3 text lines) |
28+
| `pulse` | Pulse animation |
29+
| `spin` | Spinning block animation |
30+
| `bounce` | Floating item animation |
31+
| `shake` | Shaking text animation |
32+
| `fadein` | Fade-in text animation |
33+
| `leaderboard` | Sample leaderboard |
34+
| `interactive` | Clickable display (left/right click) |
35+
| `follow` | Display that follows you |
36+
37+
## Permissions
38+
39+
```yaml
40+
displayapi.admin:
41+
description: DisplayAPI admin permission
42+
default: op
43+
```

‎docs/Animation.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Animation
2+
3+
DisplayAPI includes a keyframe-based animation engine with 12 easing functions and 8 preset animations.
4+
5+
## Pre-built Animations
6+
7+
### Pulse
8+
Scales between min and max size.
9+
```java
10+
DisplayAPI.animate(display).pulse(0.8f, 1.5f, 30).loop(true).play();
11+
// minScale maxScale ticks
12+
```
13+
14+
### Spin
15+
Rotates 360 degrees on an axis.
16+
```java
17+
DisplayAPI.animate(display).spin(AnimationBuilder.Axis.Y, 40).loop(true).play();
18+
// axis ticks
19+
// Axis options: X, Y, Z
20+
```
21+
22+
### Bounce
23+
Moves up and drops back down.
24+
```java
25+
DisplayAPI.animate(display).bounce(0.3f, 20).loop(true).play();
26+
// height ticks
27+
```
28+
29+
### Floating
30+
Gentle bobbing up and down.
31+
```java
32+
DisplayAPI.animate(display).floating(0.3f, 40).loop(true).play();
33+
// amplitude ticks
34+
```
35+
36+
### Fade In
37+
Fades from invisible to visible (TextDisplay only).
38+
```java
39+
DisplayAPI.animate(display).fadeIn(20).play();
40+
```
41+
42+
### Fade Out
43+
Fades from visible to invisible (TextDisplay only).
44+
```java
45+
DisplayAPI.animate(display).fadeOut(20).play();
46+
```
47+
48+
### Grow In
49+
Scales from 0 to target size with overshoot effect.
50+
```java
51+
DisplayAPI.animate(display).growIn(1.0f, 20).play();
52+
// targetScale ticks
53+
```
54+
55+
### Shake
56+
Rapid horizontal oscillation with decay.
57+
```java
58+
DisplayAPI.animate(display).shake(0.15f, 20).play();
59+
// intensity ticks
60+
```
61+
62+
## Custom Keyframe Animation
63+
64+
For full control, use the keyframe API:
65+
66+
```java
67+
DisplayAPI.animate(display)
68+
.keyframe(Keyframe.at(0).scale(1f).translation(0, 0, 0))
69+
.keyframe(Keyframe.at(10).scale(1.5f).translation(0, 0.5f, 0))
70+
.keyframe(Keyframe.at(20).scale(1f).translation(0, 0, 0))
71+
.easing(Easing.EASE_IN_OUT)
72+
.loop(true)
73+
.play();
74+
```
75+
76+
### Keyframe Properties
77+
78+
```java
79+
Keyframe.at(tick) // Tick position
80+
.scale(float) // Uniform scale
81+
.scale(x, y, z) // Non-uniform scale
82+
.translation(x, y, z) // Position offset
83+
.rotationX(degrees) // X-axis rotation
84+
.rotationY(degrees) // Y-axis rotation
85+
.rotationZ(degrees) // Z-axis rotation
86+
.opacity(int) // Text opacity (0-255)
87+
```
88+
89+
## Controlling Animations
90+
91+
```java
92+
// play() returns a DisplayAnimation controller
93+
DisplayAnimation anim = DisplayAPI.animate(display)
94+
.pulse(0.8f, 1.5f, 30)
95+
.loop(true)
96+
.play();
97+
98+
// Stop later
99+
anim.stop();
100+
```
101+
102+
## Easing Functions
103+
104+
See [[Easing-Functions]] for detailed descriptions of all 12 easing curves.
105+
106+
## Combining Animations
107+
108+
You can play multiple animations on the same display:
109+
110+
```java
111+
SpawnedDisplay item = DisplayAPI.item(location)
112+
.item(new ItemStack(Material.NETHER_STAR))
113+
.spawn();
114+
115+
// Float + Spin simultaneously
116+
DisplayAPI.animate(item).floating(0.3f, 40).loop(true).play();
117+
DisplayAPI.animate(item).spin(AnimationBuilder.Axis.Y, 60).loop(true).play();
118+
```

‎docs/BlockDisplay.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# BlockDisplay
2+
3+
Creates block displays using Minecraft's BlockDisplay entity.
4+
5+
## Basic Usage
6+
7+
```java
8+
SpawnedDisplay display = DisplayAPI.block(location)
9+
.block(Material.DIAMOND_BLOCK)
10+
.spawn();
11+
```
12+
13+
## Methods
14+
15+
### `.block(Material material)`
16+
Sets the block type.
17+
18+
```java
19+
.block(Material.DIAMOND_BLOCK)
20+
.block(Material.BEACON)
21+
.block(Material.TNT)
22+
```
23+
24+
### `.block(BlockData blockData)`
25+
Sets block with specific state data.
26+
27+
```java
28+
.block(Material.OAK_STAIRS.createBlockData("[facing=north,half=top]"))
29+
```
30+
31+
### `.block(String blockDataString)`
32+
Sets block from a string representation.
33+
34+
```java
35+
.block("minecraft:oak_stairs[facing=north]")
36+
```
37+
38+
## Examples
39+
40+
### Mini Block Showcase
41+
```java
42+
DisplayAPI.block(location)
43+
.block(Material.DIAMOND_BLOCK)
44+
.scale(0.3f)
45+
.billboard(Billboard.CENTER)
46+
.glow(Color.AQUA)
47+
.spawn();
48+
```
49+
50+
### Spinning Block
51+
```java
52+
SpawnedDisplay block = DisplayAPI.block(location)
53+
.block(Material.NETHER_STAR)
54+
.scale(0.5f)
55+
.spawn();
56+
57+
DisplayAPI.animate(block)
58+
.spin(AnimationBuilder.Axis.Y, 40)
59+
.loop(true)
60+
.play();
61+
```
62+
63+
See also: [[Common-Properties]] for shared builder options.

0 commit comments

Comments
 (0)