Abstract
이 모듈은 "파일 안의 파일 시스템"입니다. 하드디스크가 섹터를 묶어 파일을 만들듯, 큰 파일 하나를 4KB 조각(클러스터)으로 나눠 그 안에 작은 파일 수천 개를 담습니다. 이 페이지는 그 내부 구조를 다루고, 게임 코드에서의 사용법과 "세이브에는 무엇을 쓸 것인가"는 Unity 쪽 
File System (파일 시스템) 페이지에 있습니다.
File System (파일 시스템) 페이지에 있습니다.왜 직접 만들었나 — 풀려던 문제
원작 GameFramework 는 AssetBundle 을 에셋 단위로 잘게 쪼개 배포하는 방식을 썼고, 그러면 번들 파일이 수천 개가 됩니다. 모바일에서 이것은 세 가지 비용이 됩니다.
낱개 파일 수천 개 | 컨테이너 몇 개 |
설치·복사·삭제가 파일 수에 비례해 느리다 | 파일 몇 개만 다루면 된다 |
작은 파일도 디스크 블록 하나를 통째로 쓴다 | 내부에서 촘촘히 채운다 |
파일명과 폴더 구조가 그대로 드러난다 | 내부 파일명은 암호화되어 들어간다 |
구조를 한 장으로
graph LR
H["헤더<br>최대 파일 수·블록 수"] --> B["블록 표<br>각 파일의 위치·길이·이름 인덱스"]
B --> S["문자열 영역<br>파일명 (암호화)"]
B --> C["클러스터 영역<br>실제 데이터 (4KB 단위)"]Mermaid
복사
파일 하나를 쓰면: 이름을 문자열 영역에 넣고 → 빈 블록을 찾아 위치와 길이를 기록하고 → 클러스터 영역에 데이터를 씁니다. 지우면 블록만 "비었음"으로 표시하고, 다음에 그 크기 이하의 파일이 들어올 때 재사용합니다.
설계에서 배울 점
•
표의 크기를 만들 때 고정한다. MaxFileCount 와 MaxBlockCount 가 그것입니다. 덕분에 헤더 뒤의 표 위치가 변하지 않아 파일을 다시 쓰지 않고도 항목을 고칠 수 있습니다. 대가는 "나중에 늘릴 수 없다"입니다
•
삭제는 표시만 한다. 데이터를 실제로 지우거나 뒤를 당기지 않습니다. 빠르지만, 쓰고 지우기를 반복하면 빈틈(단편화)이 생깁니다. 그래서 블록 수를 파일 수보다 넉넉히 잡으라고 권합니다
•
부분 읽기(ReadFileSegment)가 가능하다. 큰 파일의 헤더만 읽고 싶을 때 전체를 메모리에 올리지 않아도 됩니다
이 에디션에서 다른 점 · 본문을 읽을 때 주의할 점
•
본문은 "주로 리소스 매니저에서 게임 에셋 처리를 위해 사용"된다고 하지만, 이 에디션의 리소스 계층은 Addressables 라서 파일 시스템을 쓰지 않습니다. 모듈 자체는 그대로 동작하며, 게임 코드가 직접 쓸 때만 쓰입니다.
•
이것은 압축이 아닙니다. 묶기만 하고 크기를 줄이지는 않습니다. 또 파일명 암호화는 간단한 XOR 수준이라 보안 수단으로 기대하면 안 됩니다.
•
게임 코드의 창구는 GameEntry.GetComponent<FileSystemComponent>() 입니다. CreateFileSystem / LoadFileSystem 이 돌려주는 IFileSystem 으로 읽고 씁니다.
•
쓰기 모드로 연 컨테이너는 DestroyFileSystem 으로 닫아야 파일 핸들이 풀립니다. 열어 둔 채로는 같은 경로를 다시 열 수 없고(이미 존재한다는 예외), 물리 파일을 옮기거나 지울 수도 없습니다.
파일 시스템
관련 소스 파일
•
GameFramework/FileSystem/FileSystem.cs
•
GameFramework/FileSystem/FileSystemManager.cs
•
GameFramework/FileSystem/IFileSystem.cs
•
GameFramework/FileSystem/IFileSystemManager.cs
GameFramework의 파일 시스템 컴포넌트는 가상 파일 시스템 구현체를 제공하며, 이를 통해 개발자는 게임 에셋과 리소스를 효율적으로 관리할 수 있습니다.
이 가상 파일 시스템은 여러 개의 파일을 하나의 컨테이너 파일로 묶을 수 있게 해주며, 컨테이너 내부에서 파일 생성, 읽기, 쓰기, 관리 등의 작업을 수행할 수 있습니다.
개요
이 파일 시스템은 다음과 같은 목적을 가지고 설계되었습니다:
•
파일 작업을 위한 통합 인터페이스 제공
•
여러 파일을 하나의 컨테이너 파일로 묶는 기능 지원
•
*분할(segmentation)**을 통한 효율적인 부분 읽기 가능
•
접근 권한에 따른 읽기/쓰기 작업 제공
•
중앙 관리자를 통한 파일 작업 관리
파일 시스템은 주로 리소스 매니저(Resource Manager, 리소스 관리 참고)에서 게임 에셋 처리를 위해 사용되지만, 필요 시 독립적으로 커스텀 파일 처리에도 사용할 수 있습니다.
핵심 구성 요소
파일 시스템은 다음의 주요 컴포넌트들로 구성됩니다.
IFileSystem 인터페이스
단일 파일 시스템 인스턴스와 상호작용하기 위한 계약(Contract)을 정의합니다.
컨테이너 내부에서 파일 읽기, 쓰기, 삭제, 이름 변경 등의 작업을 수행하는 메서드를 제공합니다.
주요 속성:
•
FullPath: 파일 시스템의 전체 경로
•
Access: 파일 시스템 접근 모드 (읽기, 쓰기, 읽기/쓰기)
•
FileCount: 현재 파일 시스템에 포함된 파일 개수
•
MaxFileCount: 파일 시스템이 수용할 수 있는 최대 파일 개수
주요 메서드:
•
파일 정보 작업: GetFileInfo, GetAllFileInfos, HasFile
•
파일 읽기 작업: ReadFile, ReadFileSegment
•
파일 쓰기 작업: WriteFile
•
파일 관리: SaveAsFile, RenameFile, DeleteFile
IFileSystemManager 인터페이스
여러 개의 파일 시스템 인스턴스를 관리하기 위한 계약을 정의합니다.
파일 시스템 생성, 로드, 파괴 등의 메서드를 제공합니다.
주요 메서드:
•
CreateFileSystem: 새로운 파일 시스템 생성
•
LoadFileSystem: 기존 파일 시스템 로드
•
DestroyFileSystem: 파일 시스템 파괴(물리적 파일 삭제 옵션 있음)
•
GetFileSystem: 경로로 파일 시스템 가져오기
•
GetAllFileSystems: 모든 파일 시스템 가져오기
FileSystem 구현체
IFileSystem 인터페이스를 구현한 내부 클래스입니다.
블록 기반(block-based) 접근 방식을 사용하여 컨테이너 내부의 파일을 관리합니다.
주요 내부 요소:
•
블록 데이터 관리 (파일 저장용)
•
문자열 데이터 관리 (파일명 저장용)
•
클러스터 기반 할당을 통한 효율적인 저장
파일 시스템 접근 모드
접근 모드 | 설명 | 허용 작업 |
Read | 읽기 전용 | 파일 읽기, 파일 정보 조회 |
Write | 쓰기 전용 | 파일 쓰기, 이름 변경, 삭제 |
ReadWrite | 전체 권한 | 모든 작업 |
Unspecified | 잘못된 접근 모드 | 없음 (예외 발생) |
파일 시스템 관리자
FileSystemManager는 GameFramework 모듈 중 하나로, 여러 파일 시스템의 생명주기를 관리합니다.
프레임워크 내부에서 우선순위 4를 가지며, 많은 다른 모듈보다 먼저 업데이트됩니다.
파일 시스템 생성
필요한 정보:
•
전체 경로
•
접근 모드
•
최대 파일 개수
•
최대 블록 개수
파일 시스템 로드
필요한 정보:
•
전체 경로
•
접근 모드
파일 작업
파일 시스템은 가상 파일 시스템 컨테이너 내에서 포괄적인 파일 관리 작업을 제공합니다.
파일 읽기
•
전체 파일 읽기: ReadFile
•
파일 일부 읽기: ReadFileSegment
양쪽 모두 바이트 배열, 스트림, 시작 인덱스 및 길이 지정 등 다양한 오버로드를 지원합니다.
파일 쓰기
•
바이트 배열에서 쓰기: WriteFile
•
스트림에서 쓰기: WriteFile
•
물리적 파일에서 쓰기: WriteFile
추가 파일 작업
•
SaveAsFile: 컨테이너 내부 파일을 물리적 파일로 저장
•
RenameFile: 컨테이너 내부 파일 이름 변경
•
DeleteFile: 컨테이너 내부 파일 삭제
내부 구현 세부사항
파일 시스템은 효율적인 저장·검색을 위해 블록 기반 구조를 사용합니다.
•
클러스터(Cluster): 고정 크기 저장 단위 (기본 4KB)
•
블록(Block): 파일 메타데이터 (클러스터 인덱스, 길이, 문자열 인덱스)
•
StringData: 암호화된 파일명 저장 공간
메모리 최적화
•
사용하지 않는 블록을 추적하여 재활용
•
블록 병합으로 조각화 최소화
•
문자열 데이터 풀링을 통한 재사용
사용 지침
베스트 프랙티스
•
읽기 전용 리소스는 Read 모드 사용
•
수정이 필요한 경우에만 ReadWrite 모드 사용
•
MaxFileCount ≤ MaxBlockCount 권장
•
더 이상 필요 없는 경우 DestroyFileSystem 호출로 자원 해제
(물리 파일 삭제 여부는 상황에 따라 결정)
자주 하는 실수
•
읽기 전용 파일 시스템에 쓰기 시도
•
최대 파일 개수 초과
•
파일 작업 중 예외 처리 누락
•
올바른 파일 시스템 헬퍼 설정 실패
요약
파일 시스템 컴포넌트는 파일을 묶고 관리하는 강력한 가상 파일 시스템입니다.
GameFramework의 다른 모듈과 긴밀하게 연동되며, 내부적으로 복잡한 블록 관리·메모리 최적화·접근 제어를 처리하면서도 외부에는 깔끔한 인터페이스를 제공합니다.