Skip to content

RTUStudio/FieldZone

BranchesTags

Repository files navigation

FieldZone

다각형 기반 지역 관리 플러그인. 자유 형태의 다각형, 사각형, 레이캐스트 모드로 지역을 생성하고, 플래그를 설정하여 경계 경고 시스템 등을 구성할 수 있습니다.

의존성: RSFramework

사용자 가이드

명령어

기본 명령어: /fieldzone (별칭: /지역)

명령어 설명
/fieldzone wand 지역 선택 도구를 받습니다
/fieldzone create <이름> 선택한 점들로 지역을 생성합니다
/fieldzone remove <지역> 지역을 제거합니다
/fieldzone teleport <지역> 지역의 중심으로 이동합니다
/fieldzone list 모든 지역 목록을 확인합니다
/fieldzone info <지역> 지역의 상세 정보를 확인합니다 (면적, 둘레, 중심, 플래그 등)
/fieldzone clear 선택한 모든 점을 초기화합니다
/fieldzone particle 파티클 표시를 켜거나 끕니다
/fieldzone flag set <지역> <플래그> [true|false] 지역에 플래그 값을 설정합니다 (기본: true)
/fieldzone flag clear <지역> <플래그> 지역에서 플래그를 해제합니다 (NONE 상태로 복귀)
/fieldzone flag list <지역> 지역의 플래그 목록을 확인합니다
/fieldzone reload 설정을 다시 불러옵니다

선택 모드

도구를 들고 **우클릭(Shift)**으로 모드를 전환할 수 있습니다.

모드 설명
자유 (FREE) 클릭한 위치마다 점이 추가됩니다. 자유로운 다각형 생성에 적합합니다.
사각형 (SQUARE) 두 지점을 선택하면 자동으로 사각형 영역이 생성됩니다.
레이캐스트 (RAYCAST) 바라보는 방향의 블록에 점을 추가합니다. (최대 거리: 설정 가능)

도구 조작:

  • 좌클릭: 점 추가 (자유/레이캐스트 모드) 또는 첫 번째/두 번째 지점 선택 (사각형 모드)
  • 우클릭: 마지막 점 제거
  • Shift + 우클릭: 선택 모드 전환

플래그

플래그는 namespace:key 형식을 사용합니다. 내장 플래그는 fieldzone 네임스페이스를 사용하며, 외부 플러그인은 자신만의 네임스페이스로 커스텀 플래그를 등록할 수 있습니다.

플래그 설명
fieldzone:warning 플레이어가 지역 경계에 가까이 가면 빨간색 파티클로 경계면을 표시합니다

명령어에서 fieldzone: 접두사는 생략 가능합니다. (예: /fz flag set spawn warning)

설정 파일

Global.yml — 전역 설정

항목 기본값 설명
clean-unregistered-flags false 소유자 플러그인이 로드되었지만 플래그를 등록하지 않았을 때 해당 플래그를 자동 삭제할지 여부
wand.item minecraft:blaze_rod 도구 아이템 (CustomItems 형식)
wand.raycast-max-range 200 레이캐스트 최대 거리
wand.particle.interval 2 파티클 표시 간격 (틱)
wand.particle.density 0.05 파티클 밀도 (낮을수록 촘촘)
wand.particle.wave-gap 10 파도 간격 (블록)
wand.particle.wave-phase-step 0.1 파도 상승 단계
wand.particle.vertical-range 64 수직 표시 범위 (±블록)

Flag.yml — 경고 시스템 설정

항목 기본값 설명
warning.distance 2.75 경고 감지 거리 (블록)
warning.particle.type OMINOUS_SPAWNING 경고 파티클 종류
warning.particle.cooldown 29 파티클 쿨다운 (틱)
warning.particle.interval 0.25 샘플링 간격 (블록)

PlaceholderAPI

Placeholder 설명
%fieldzone_region% 현재 위치한 지역 이름 (없으면 "빈 공간")
%fieldzone_count% 총 지역 개수
%fieldzone_area_<이름>% 특정 지역의 면적
%fieldzone_points_<이름>% 특정 지역의 점 개수

권한

권한 기본 설명
fieldzone.wand OP 도구 관련 명령어 사용

개발자 가이드

의존성 추가

repositories {
    maven {
        name = "RTUStudio"
        url = uri("https://repo.codemc.io/repository/rtustudio/")
    }
}

dependencies {
    compileOnly("kr.rtustudio:fieldzone:1.2.0")
}

plugin.yml에 의존성을 추가하세요:

depend:
  - FieldZone

API 사용법

모든 API는 FieldZoneAPI 클래스의 static 메소드로 제공됩니다.

지역 조회

// Location으로 지역 조회
Region region = FieldZoneAPI.getRegion(player.getLocation());

// 이름으로 지역 조회
Region region = FieldZoneAPI.getRegion("spawn");

// 모든 지역 목록
List<Region> regions = FieldZoneAPI.getRegions();

// 총 지역 개수
int count = FieldZoneAPI.getRegionCount();

위치 판정

// 해당 위치가 지역 내부인지 확인
boolean inside = FieldZoneAPI.isInRegion(player.getLocation());

// 해당 위치에 특정 플래그의 상태 확인 (TRUE / FALSE / NONE)
FlagState state = FieldZoneAPI.hasFlag(player.getLocation(), RegionFlag.WARNING);
boolean active = state.toBoolean();  // NONE과 FALSE는 false

지역 정보

// 면적 (㎡)
double area = FieldZoneAPI.getArea("spawn");

// 둘레 (블록)
double perimeter = FieldZoneAPI.getPerimeter("spawn");

// 중심점
Point center = FieldZoneAPI.getCenter("spawn");

Region 객체

Region은 record 타입이며 다음 필드를 가집니다:

필드 타입 설명
uuid() UUID 고유 식별자
name() String 지역 이름
pos() PolygonPos 다각형 위치 데이터 (점 목록, 월드, 면적, 둘레, 중심)
flags() Map<RegionFlag, Boolean> 설정된 플래그와 값 
Region region = FieldZoneAPI.getRegion("spawn");
if (region != null) {
    String name = region.name();
    String world = region.pos().world();
    double area = region.pos().area();

    // hasFlag()는 FlagState를 반환 (TRUE / FALSE / NONE)
    FlagState state = region.hasFlag(RegionFlag.WARNING);
    if (state.toBoolean()) {
        // 경고 활성화됨
    }
}

커스텀 플래그 시스템

FieldZone은 외부 플러그인이 자체 플래그를 등록하고 활용할 수 있는 확장 가능한 플래그 시스템을 제공합니다. WorldGuard처럼, 외부 플러그인은 자신만의 네임스페이스를 가진 플래그를 추가할 수 있습니다.

RegionFlag 구조

RegionFlag는 namespace(소유자)와 key(이름)로 구성된 레코드입니다:

// FieldZone 내장 플래그
RegionFlag.WARNING           // → "fieldzone:warning"

// 커스텀 플래그 생성 (RegionFlag.create 사용 권장)
RegionFlag.create(this, "no_lightning")  // → "myplugin:no_lightning"
RegionFlag.create(this, "safe_zone")     // → "myplugin:safe_zone"

FlagState (3-상태)

hasFlag()는 boolean이 아닌 FlagState enum을 반환합니다:

상태 의미 toBoolean()
TRUE 플래그가 명시적으로 true로 설정됨 true
FALSE 플래그가 명시적으로 false로 설정됨 false
NONE 플래그가 설정되지 않음 (데이터에 저장되지 않음) false

플래그 등록 및 해제

// onEnable()에서 등록
RegionFlag myFlag = RegionFlag.create(this, "no_lightning");
FieldZoneAPI.registerFlag(myFlag);

// onDisable()에서 해제
FieldZoneAPI.unregisterFlag(myFlag);

등록된 플래그는 자동으로 /fieldzone flag set 명령어의 탭 자동완성에 나타납니다.

플래그 활용

// 특정 위치에 해당 플래그가 설정되어 있는지 확인
FlagState state = FieldZoneAPI.hasFlag(location, myFlag);
if (state.toBoolean()) {
    // 플래그가 true로 설정된 지역 내부
}

// 3-상태를 활용한 세밀한 제어
FlagState state = FieldZoneAPI.hasFlag(location, myFlag);
switch (state) {
    case TRUE  -> // 명시적으로 활성화됨
    case FALSE -> // 명시적으로 비활성화됨
    case NONE  -> // 설정 없음, 기본 동작 적용
}

미등록 플래그 보존 정책

clean-unregistered-flags 설정에 따라 미등록 플래그의 처리 방식이 달라집니다:

상황 false (기본) true
소유자 플러그인 미로드 보존 ✅ 보존 ✅
소유자 플러그인 로드됨 + 플래그 미등록 보존 ✅ 삭제 🗑️
소유자 플러그인 로드됨 + 플래그 등록됨 정상 사용 정상 사용

이는 플러그인 업데이트로 플래그가 제거된 경우를 감지하기 위한 것입니다. 소유자 플러그인이 활성 상태임에도 해당 플래그를 등록하지 않았다면, 더 이상 사용하지 않는 것으로 판단하고 정리합니다.

활용 예시: 번개 방지 플래그

다음은 번개를 발생시키는 플러그인이 FieldZone의 플래그 시스템을 활용하여 특정 지역에서 번개를 차단하는 완전한 예시입니다:

package kr.example.lightning;

import kr.rtustudio.fieldzone.FieldZoneAPI;
import kr.rtustudio.fieldzone.region.FlagState;
import kr.rtustudio.fieldzone.region.RegionFlag;
import org.bukkit.Location;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.weather.LightningStrikeEvent;
import org.bukkit.plugin.java.JavaPlugin;

/**
 * 번개 플러그인 예시.
 * FieldZone에 'no_lightning' 플래그를 등록하고,
 * 해당 플래그가 true로 설정된 지역에서는 번개를 차단합니다.
 */
public class LightningPlugin extends JavaPlugin implements Listener {

    // 플래그를 필드로 선언
    private RegionFlag noLightning;

    @Override
    public void onEnable() {
        // RegionFlag.create(this, key) — 플러그인 이름이 자동으로 namespace가 됨
        noLightning = RegionFlag.create(this, "no_lightning");

        // FieldZone 레지스트리에 커스텀 플래그 등록
        // → /fz flag set <지역> LightningPlugin:no_lightning 으로 사용 가능
        // → /fz flag set <지역> LightningPlugin:no_lightning false 로 명시적 비활성화도 가능
        FieldZoneAPI.registerFlag(noLightning);

        getServer().getPluginManager().registerEvents(this, this);
        getLogger().info("LightningPlugin enabled — registered 'lightning:no_lightning' flag");
    }

    @Override
    public void onDisable() {
        // 플러그인 종료 시 플래그 해제
        FieldZoneAPI.unregisterFlag(noLightning);
    }

    @EventHandler
    private void onLightningStrike(LightningStrikeEvent event) {
        Location location = event.getLightning().getLocation();

        // FlagState를 통한 3-상태 확인
        FlagState state = FieldZoneAPI.hasFlag(location, noLightning);

        // toBoolean()으로 간단히 확인 (TRUE만 true, FALSE와 NONE은 false)
        if (state.toBoolean()) {
            event.setCancelled(true);
        }
    }
}

사용 흐름:

  1. 서버에 FieldZone과 LightningPlugin이 함께 설치되어 있습니다.
  2. LightningPlugin이 활성화되면 lightning:no_lightning 플래그가 자동 등록됩니다.
  3. 관리자가 /fz flag set spawn LightningPlugin:no_lightning 명령어를 실행합니다 → TRUE 설정.
  4. 이제 spawn 지역에서는 번개가 차단됩니다.
  5. /fz flag set spawn LightningPlugin:no_lightning false → 명시적으로 FALSE 설정 (차단 해제).
  6. /fz flag clear spawn LightningPlugin:no_lightning → NONE 상태로 복귀 (데이터에서 삭제).
  7. LightningPlugin을 제거하면:
    • clean-unregistered-flags: false → 플래그 데이터가 보존되어, 다시 설치하면 바로 작동합니다.
    • clean-unregistered-flags: true → 소유자 플러그인이 없으므로 데이터가 보존됩니다. (소유자가 로드되었는데 등록을 안 했을 때만 삭제)

About

2D Polygonal Region Plugin

Resources

Readme

License

GPL-3.0 license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages