저장 데이터와 버전

모드가 저장하는 데이터의 형식을 바꾸면 이미 저장된 월드의 옛 데이터를 새 형식으로 변환해야 합니다. Poly 모드 로더는 세 종류의 저장 데이터에 같은 방식의 버전 관리와 마이그레이션(DataMigration)을 제공합니다.

저장 데이터	버전 지정
월드 저장소(world.storage)	StorageOptions.DEFAULT.withVersion(version, migration)
블록 엔티티 데이터	BlockEntityDefinition.builder().dataVersion(version, migration)
엔티티 데이터(entityData)	EntityDataOptions.DEFAULT.withVersion(version, migration)

월드 저장소

/** 버전 2에서 message의 이름을 motd로 바꿈. */
static final StorageOptions WORLD_INFO_OPTIONS = StorageOptions.DEFAULT
        .withVersion(2, (data, fromVersion) -> {        // 옛 버전 데이터를 불러올 때 한 번 실행
            if (fromVersion < 2 && data.has("message")) {
                data.putString("motd", data.getString("message", ""));
                data.remove("message");
            }
        })
        .syncedToClients();

StoredData info = world.storage(ResourceId.of("my_mod", "world_info"), WORLD_INFO_OPTIONS);

• 버전은 저장 데이터의 poly_version(예약 키)에 기록합니다.
• 저장된 버전이 현재보다 옛 버전이면 마이그레이션을 실행합니다.
• 저장된 버전이 더 새 버전이면(모드를 낮은 버전으로 되돌린 경우) 데이터를 그대로 두고 POLY-STORAGE-001을 기록합니다.
• 같은 저장소 ID를 다른 옵션으로 열면 IllegalArgumentException이 발생합니다. 옵션은 상수로 선언해 같은 것을 재사용하세요.

블록 엔티티 데이터

BlockEntityDefinition.builder()
        .dataVersion(2, (data, from) -> { /* 옛 저장 데이터 변환 */ })
        .build();

월드 저장소와 똑같이 동작합니다.

엔티티 데이터

EntityDataKey MOOD = mod.content().entityData("golem_mood", EntityDataOptions.DEFAULT
        .syncedToTrackers()
        .withVersion(2, (data, fromVersion) -> {
            if (fromVersion < 2 && data.has("feeling")) {
                data.putString("mood", data.getString("feeling", ""));
                data.remove("feeling");
            }
        }));

• 버전은 키마다 저장 트리의 예약 키 poly_version에 기록합니다.
• /data merge로 넣은 데이터도 같은 변환을 거칩니다.

마이그레이션 작성 요령

fromVersion과 비교해 단계별로 변환하세요(if (fromVersion < 2) …, if (fromVersion < 3) …). 그러면 아주 오래된 데이터도 차례로 최신 형식이 됩니다. 마이그레이션은 게임 테스트로 검증할 수 있습니다.

월드 백업

모드가 빠지거나 버전이 바뀐 월드는 불러오기 전에 Poly 모드 로더가 자동으로 백업합니다. 자세한 내용은 운영을 참고하세요.