LuminaFolia 위에서
일반 플러그인도 그대로.
Folia, with your
regular plugins intact.
Lumina는 Folia를 기반으로 한 마인크래프트 서버입니다. 지역마다 병렬로 틱을 돌리는 Folia 구조는 그대로 두고, folia-supported 표시가 없는 Paper 플러그인도 로딩해서 안전하게 실행합니다.
Lumina is a Minecraft server built on Folia. It keeps Folia's parallel, per-region ticking and also loads Paper plugins that lack folia-supported, running them safely.
지역별 병렬 틱 유지
Parallel region ticking
Folia를 지원하는 플러그인과 월드는 원래처럼 지역마다 다른 스레드에서 돕니다. 성능 손해가 없습니다.
Folia-ready plugins and worlds keep ticking on separate threads per region, at no extra cost.
일반 플러그인 호환
Regular plugins work
BukkitScheduler, 동기 teleport, 스코어보드 API, 꺼져 있던 바닐라 명령어를 다시 쓸 수 있습니다.
BukkitScheduler, sync teleport, the scoreboard API and previously disabled vanilla commands are back.
옵션 하나로 순정 Folia
One flag for stock Folia
-Dfolia.legacyCompat=false를 주면 호환 모드가 꺼지고 Folia와 똑같이 동작합니다.
Pass -Dfolia.legacyCompat=false and the server behaves exactly like Folia.
다운로드Downloads
버전을 고르세요. 모든 빌드는 GitHub Actions가 공개된 소스에서 직접 만들어 GitHub Releases에 올립니다. 처음 실행할 때 Mojang 서버 파일을 자동으로 받습니다.
Pick a version. Every build is produced from the public source by GitHub Actions and published on GitHub Releases. The Mojang server is downloaded automatically on first start.
빌드 목록을 불러오는 중…Loading builds…
동작 방식How it works
핵심은 LegacyCompat 클래스 하나입니다. 플러그인이 Folia를 지원하면 Folia 방식 그대로, 지원하지 않으면 모든 지역을 잠깐 멈춘 상태(stop-the-world)에서 혼자 실행합니다.
The core is a single class, LegacyCompat. Folia-ready plugins run exactly as on Folia; others run alone while every region is briefly paused (stop-the-world).
| 상황Situation | 처리Handling | ||
|---|---|---|---|
| 일반 플러그인이 듣는 동기 이벤트 | Sync events a regular plugin listens to | 이벤트 전체를 runExclusive로 실행 | The whole event runs inside runExclusive |
| BukkitScheduler 동기 작업 | BukkitScheduler sync tasks | 전역 틱마다 확인해서, 실행할 작업이 있는 틱에만 runExclusive | Checked every global tick; runExclusive only when tasks are due |
| 비동기 작업 | Async tasks | 기존 Paper 방식 그대로 | Unchanged from Paper |
| 모든 명령어, 일반 플러그인의 onEnable / onDisable | All commands, onEnable / onDisable of regular plugins | runExclusive 안에서 실행 | Run inside runExclusive |
| 다른 지역의 블록 수정 / 엔티티 추가 / teleport | Block edits / entity adds / teleport in another region | 스레드의 "현재 지역"을 그 지역으로 잠깐 바꿔서 실행 (inRegionAt) | The thread's current region is switched temporarily (inRegionAt) |
| 로드되지 않은 청크의 동기 로딩 | Sync load of an unloaded chunk | 잠금을 잠깐 풀고 요청합니다. 기다리는 스레드가 그 지역 작업을 직접 처리해서, 틱 스레드가 1~2개여도 멈추지 않습니다 | The lock is released while waiting and the waiting thread processes the region's tasks itself, so it never stalls even with 1–2 tick threads |
| 서버 시작 | Server startup | 지역 스레드를 POSTWORLD 플러그인 켜기 전에 시작하고, 전역 틱(접속, 콘솔)은 그다음에 시작 | Region threads start before POSTWORLD plugins enable; the global tick (logins, console) starts afterwards |
runExclusive 순서Inside runExclusive
- 다른 지역들이 지금 돌고 있는 틱을 끝낼 때까지 기다리고, 새 틱은 막습니다.
- 혼자 실행하는 동안 스레드 소유 검사를 통과시킵니다.
- 추가·제거된 엔티티와 청크는 그 위치를 소유한 지역에 기록합니다.
- 기다리는 스레드는 자신을 "멈춤"으로 표시해서 데드락을 막습니다.
- Waits for running region ticks to finish and blocks new ones.
- Thread ownership checks pass while running alone.
- Added/removed entities and chunks are recorded in the region that owns the position.
- Waiting threads mark themselves paused, which prevents deadlocks.
아직 꺼져 있는 것Still disabled
/reload,/datapack: Folia에서는 메인 스레드 큐가 돌지 않아 서버가 멈춥니다/save-all: 저장이 지역 단위입니다. 자동 저장과/stop저장은 정상입니다/perf,/test: 메인 스레드 전용 기능입니다createWorld/unloadWorld: Folia 원본에서도 아직 없습니다
/reload,/datapack: the main-thread queue doesn't run on Folia, so the server would hang/save-all: saving is per region; autosave and saving on/stopwork/perf,/test: main-thread only featurescreateWorld/unloadWorld: not in upstream Folia either
설정Configuration
JVM 옵션으로 정합니다. java 명령의 -jar 앞에 붙이세요.
Set as JVM flags, before -jar in your java command.
| 옵션Flag | 설명Description |
|---|---|
-Dfolia.legacyCompat=false | 호환 모드 전체를 끕니다 (기본값 true)Turns compatibility mode off (default true) |
-Dfolia.legacyCommands=false | 다시 켠 명령어와 명령어 전역 실행만 끕니다 (기본값 true)Turns off only the re-enabled commands (default true) |
-Dfolia.legacyCompat.slowWarnMs=100 | 전역 실행이 이 시간(ms)보다 길면 경고합니다 (기본값 100)Warns when an exclusive section takes longer than this many ms (default 100) |
알아 두어야 할 점Caveats
- 일반 플러그인이 많이 일할수록 서버가 단일 스레드처럼 느려집니다.
- Folia 내부 잠금을 쥔 상태에서 일반 플러그인 이벤트가 발생하면 이론상 데드락이 날 수 있습니다. 멈추면 워치독이 스레드 덤프를 남깁니다.
- NMS나 CraftBukkit 내부를 직접 건드리는 플러그인은 깨질 수 있습니다.
- PaperMC는 Lumina를 지원하지 않습니다. Lumina에서 생긴 문제를 Paper/Folia에 신고하지 마세요.
- The more work regular plugins do, the more the server behaves single-threaded.
- A deadlock is theoretically possible if a regular plugin event fires while a Folia internal lock is held. The watchdog writes a thread dump if it hangs.
- Plugins that touch NMS or CraftBukkit internals may break.
- PaperMC does not support Lumina. Don't report Lumina problems to Paper/Folia.