Skip to content

Commit 7a64ac6

Browse files
wjddusrb03claude
wjddusrb03
and
claude
committed
Add README (EN/KO) and PlaceholderAPI utility
- README.md with full API documentation and comparison table - README_KO.md Korean translation - PlaceholderUtil for safe PlaceholderAPI integration - Log PlaceholderAPI detection on enable Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 851eb01 commit 7a64ac6

4 files changed

Lines changed: 532 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
# DisplayAPI
2+
3+
**Lightweight Display Entity API for Paper 1.21.4+**
4+
5+
A developer-friendly framework for creating and managing Display entities (TextDisplay, BlockDisplay, ItemDisplay) with zero external dependencies.
6+
7+
[한국어 README](README_KO.md)
8+
9+
---
10+
11+
## Why DisplayAPI?
12+
13+
| Feature | DisplayAPI | DecentHolograms | FancyHolograms | HologramLib |
14+
|---------|-----------|-----------------|----------------|-------------|
15+
| Display Entity based | Yes | No (ArmorStand) | Yes | Yes |
16+
| Zero dependencies | Yes | No | No | PacketEvents |
17+
| Animation engine | Yes (12 easings) | No | Limited | No |
18+
| Click detection | Yes | No | No | No |
19+
| Entity follow | Yes | No | No | No |
20+
| Per-player visibility | Yes | Yes | Yes | Yes |
21+
| Persistence | Yes (YAML) | Yes | Yes | No |
22+
| Builder pattern API | Yes | No | No | Partial |
23+
| PlaceholderAPI | Yes | Yes | Yes | No |
24+
| Open source (MIT) | Yes | Yes | Yes | Yes |
25+
26+
## Quick Start
27+
28+
### For Plugin Developers
29+
30+
Add DisplayAPI as a dependency in your `plugin.yml`:
31+
```yaml
32+
depend:
33+
- DisplayAPI
34+
```
35+
36+
### Basic Usage
37+
38+
```java
39+
// Text hologram
40+
SpawnedDisplay display = DisplayAPI.text(location)
41+
.text(Component.text("Hello!").color(NamedTextColor.GOLD))
42+
.billboard(Billboard.CENTER)
43+
.shadowed(true)
44+
.noBackground()
45+
.spawn();
46+
47+
// Block display
48+
DisplayAPI.block(location)
49+
.block(Material.DIAMOND_BLOCK)
50+
.scale(0.5f)
51+
.glow(Color.AQUA)
52+
.spawn();
53+
54+
// Item display
55+
DisplayAPI.item(location)
56+
.item(new ItemStack(Material.DIAMOND_SWORD))
57+
.billboard(Billboard.CENTER)
58+
.spawn();
59+
```
60+
61+
### Damage Popup
62+
63+
```java
64+
DisplayAPI.popup(entity.getLocation().add(0, 2, 0))
65+
.text(Component.text("-25").color(NamedTextColor.RED))
66+
.duration(30)
67+
.startScale(1.5f)
68+
.endScale(0.3f)
69+
.visibleTo(attacker)
70+
.spawn();
71+
```
72+
73+
### Animations
74+
75+
```java
76+
// Pre-built animations
77+
DisplayAPI.animate(display).pulse(0.8f, 1.5f, 30).loop(true).play();
78+
DisplayAPI.animate(display).spin(AnimationBuilder.Axis.Y, 40).loop(true).play();
79+
DisplayAPI.animate(display).floating(0.3f, 40).loop(true).play();
80+
DisplayAPI.animate(display).shake(0.15f, 20).play();
81+
DisplayAPI.animate(display).fadeIn(20).play();
82+
DisplayAPI.animate(display).fadeOut(20).play();
83+
DisplayAPI.animate(display).growIn(1.0f, 20).play();
84+
DisplayAPI.animate(display).bounce(0.3f, 20).loop(true).play();
85+
86+
// Custom keyframe animation
87+
DisplayAPI.animate(display)
88+
.keyframe(Keyframe.at(0).scale(1f).translation(0, 0, 0))
89+
.keyframe(Keyframe.at(20).scale(2f).translation(0, 1f, 0))
90+
.keyframe(Keyframe.at(40).scale(1f).translation(0, 0, 0))
91+
.easing(Easing.EASE_IN_OUT)
92+
.loop(true)
93+
.play();
94+
```
95+
96+
**12 Easing Functions:** LINEAR, EASE_IN, EASE_OUT, EASE_IN_OUT, CUBIC_IN/OUT/IN_OUT, QUART_IN/OUT/IN_OUT, EASE_IN_BACK, EASE_OUT_BACK, BOUNCE, ELASTIC
97+
98+
### Clickable Display
99+
100+
```java
101+
DisplayAPI.interactive(location)
102+
.text(Component.text("Click me!").color(NamedTextColor.GREEN))
103+
.hitbox(1.5f, 1.0f)
104+
.onClick(player -> player.sendMessage("Left clicked!"))
105+
.onRightClick(player -> player.sendMessage("Right clicked!"))
106+
.cooldown(200)
107+
.spawn();
108+
```
109+
110+
### Entity Following
111+
112+
```java
113+
DisplayAPI.follow(display, player)
114+
.offset(0, 2.5, 0)
115+
.smoothTeleport(3)
116+
.start();
117+
```
118+
119+
### Display Group
120+
121+
```java
122+
DisplayGroup group = DisplayAPI.group("my-group", anchorLocation);
123+
group.add(display1);
124+
group.add(display2);
125+
group.add(display3);
126+
127+
group.teleport(newLocation); // Move all together
128+
group.remove(); // Remove all
129+
```
130+
131+
### Leaderboard
132+
133+
```java
134+
// Static data
135+
DisplayAPI.leaderboard(location)
136+
.title("Kill Rankings")
137+
.entry("Player_A", 150)
138+
.entry("Player_B", 120)
139+
.maxRows(10)
140+
.spawn();
141+
142+
// Dynamic (auto-updating)
143+
DisplayAPI.leaderboard(location)
144+
.title("Kill Rankings")
145+
.dataSupplier(() -> getKillStats())
146+
.updateInterval(100)
147+
.spawn();
148+
```
149+
150+
### Per-Player Visibility
151+
152+
```java
153+
DisplayAPI.text(location)
154+
.text(Component.text("Only you can see this"))
155+
.visibleTo(player)
156+
.spawn();
157+
```
158+
159+
### Persistence
160+
161+
```java
162+
DisplayAPI.text(location)
163+
.text(Component.text("I survive restarts"))
164+
.persistent(true)
165+
.id("permanent-hologram")
166+
.spawn();
167+
```
168+
169+
### Runtime Updates
170+
171+
```java
172+
SpawnedDisplay display = DisplayAPI.getById("my-display");
173+
174+
display.updateText(Component.text("Updated!"));
175+
display.updateBlock(Material.GOLD_BLOCK);
176+
display.updateItem(new ItemStack(Material.BOW));
177+
display.setGlowing(true);
178+
display.setGlowColor(Color.RED);
179+
display.setBillboard(Billboard.FIXED);
180+
display.smoothTeleport(newLocation, 5);
181+
```
182+
183+
### PlaceholderAPI Support
184+
185+
```java
186+
import com.wjddusrb03.displayapi.util.PlaceholderUtil;
187+
188+
// Parse placeholders for a player
189+
String parsed = PlaceholderUtil.parse(player, "Health: %player_health%");
190+
Component comp = PlaceholderUtil.parse(player, component);
191+
```
192+
193+
## Common Properties (All Builders)
194+
195+
| Method | Description |
196+
|--------|-------------|
197+
| `.billboard(Billboard)` | CENTER, FIXED, HORIZONTAL, VERTICAL |
198+
| `.viewRange(float)` | Render distance multiplier |
199+
| `.scale(float)` | Uniform scale |
200+
| `.scale(x, y, z)` | Non-uniform scale |
201+
| `.translation(x, y, z)` | Position offset |
202+
| `.glow(Color)` | Glowing outline with color |
203+
| `.brightness(block, sky)` | Fixed brightness |
204+
| `.shadow(radius, strength)` | Shadow settings |
205+
| `.visibleTo(Player...)` | Per-player visibility |
206+
| `.persistent(boolean)` | Survive server restarts |
207+
| `.id(String)` | Unique identifier |
208+
209+
## Admin Commands
210+
211+
| Command | Description |
212+
|---------|-------------|
213+
| `/dapi test <type>` | Spawn test display (14 types) |
214+
| `/dapi list` | List active displays |
215+
| `/dapi remove <id>` | Remove by ID |
216+
| `/dapi removeall` | Remove all displays |
217+
| `/dapi save` | Save persistent displays |
218+
| `/dapi reload` | Reload config |
219+
| `/dapi info` | Plugin info |
220+
221+
Permission: `displayapi.admin` (default: op)
222+
223+
## Requirements
224+
225+
- Paper 1.21.4+
226+
- Java 21+
227+
- (Optional) PlaceholderAPI
228+
229+
## Installation
230+
231+
1. Download `DisplayAPI-1.0.0.jar` from [Releases](https://github.com/wjddusrb03/DisplayAPI/releases)
232+
2. Place in your server's `plugins/` folder
233+
3. Restart the server
234+
235+
## License
236+
237+
MIT License

0 commit comments

Comments
 (0)