파일 시스템
관련 소스 파일
•
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의 다른 모듈과 긴밀하게 연동되며, 내부적으로 복잡한 블록 관리·메모리 최적화·접근 제어를 처리하면서도 외부에는 깔끔한 인터페이스를 제공합니다.
원하시면 제가 여기에 구조 다이어그램을 그려서, 이 파일 시스템의 클러스터·블록·스트링 데이터 관계를 시각적으로 보여드릴 수도 있습니다.
그렇게 하면 Unity나 GameFramework 내부에서 데이터 흐름을 한 번에 이해할 수 있습니다.
그걸 그려드릴까요?