1) 폴더/깃 구조 결정
D:\Github\ToyboxNightmare\
External\
GameFramework\ ← 외부 프레임워크(별도 프로젝트/서브모듈)
Assets\
Plugins\ ← Unity가 참조할 DLL/PDB 위치
Plain Text
복사
•
이유: Assets 밖에 두면 Unity가 임포트/컴파일하지 않아 unsafe/참조 오류가 사라짐.
2) External\GameFramework 프로젝트 설정(.csproj)
•
프로젝트 형식: Class Library
•
Target: .NET Standard 2.1 (또는 Unity 설정이 .NET 4.x이면 거기에 맞춤)
•
Debugging information: portable PDB
•
(필요 시) /unsafe ON → 사전 컴파일 DLL이므로 Unity 전역 “Allow ‘unsafe’”는 필요 없음.
•
NuGet 의존성: (개발·빌드용) SharpZipLib 참조 추가 가능
단, Unity 쪽에 Unity.SharpZipLib 패키지를 추가했으므로 Assets로는 SharpZipLib DLL을 복사하지 않는다 (중복 타입 방지).
3) 빌드 산출물 → Unity로 자동 복사 (Post-build)
프로젝트 속성 → Build Events → Post-build event 에 아래 스크립트 등록
:: === Copy to Unity (relative from csproj) ===
set "DEST=$(ProjectDir)..\..\Assets\Plugins"
if not exist "%DEST%" mkdir "%DEST%"
:: 깨끗이 정리
del /Q "%DEST%\$(TargetName).dll" 2>nul
del /Q "%DEST%\$(TargetName).pdb" 2>nul
:: (중요) Unity.SharpZipLib 패키지를 쓸 것이므로, SharpZipLib는 복사/동봉하지 않음
del /Q "%DEST%\ICSharpCode.SharpZipLib.dll" 2>nul
del /Q "%DEST%\ICSharpCode.SharpZipLib.pdb" 2>nul
:: 공통: 내 프레임워크 DLL 복사
if exist "$(TargetDir)$(TargetName).dll" copy /Y "$(TargetDir)$(TargetName).dll" "%DEST%\"
:: Debug일 때만 PDB 복사(에디터 스텝-인 디버깅)
if /I "$(ConfigurationName)"=="Debug" (
if exist "$(TargetDir)$(TargetName).pdb" copy /Y "$(TargetDir)$(TargetName).pdb" "%DEST%\"
)
echo Copied $(ConfigurationName) to: %DEST%
Shell
복사
•
경로 해석: $(ProjectDir)..\..\Assets\Plugins → External\GameFramework\에서 두 단계 위가 프로젝트 루트.
•
하나의 DLL만 유지하도록 기존 파일 삭제 후 복사.
4) Unity 쪽 설정
•
Package Manager에서 Unity.SharpZipLib(com.unity.sharp-zip-lib) 설치
→ ICSharpCode.SharpZipLib 어셈블리를 Unity가 제공.
•
Api Compatibility Level: .NET 4.x(권장)
•
(asmdef 사용하는 경우)
◦
내 게임 코드 asmdef의 Override References 꺼두면 Plugins의 DLL/패키지 DLL을 자동 참조
◦
Override References가 켜져 있다면 Assembly Definition References에 GameFramework.dll(프리컴파일)만 넣으면 됨.
(SharpZipLib는 패키지가 제공하므로 따로 추가 X)
5) 디버깅/릴리즈 운용
•
Editor에서 디버깅: Debug 빌드 + PDB 복사 → VS에서 Attach to Unity 후 스텝-인 가능
•
공유/CI/릴리즈: Release 빌드 → DLL만 복사(필요 시 PDB도 가능하지만 최적화로 스텝이 튈 수 있음)
•
Plugins에는 동시에 하나의 변형만(Debug/Release 섞지 않기)
6) (선택) 소스 직접 디버깅이 필요할 때
•
잠깐 소스 그대로 보고 싶으면 External/.../Runtime을 Assets/...에 심볼릭 링크/정크션으로 노출하거나,
로컬 UPM 패키지(manifest.json에 file:../External/GameFramework)로 등록 → 디버깅 끝나면 링크/의존성 해제.
•
이때 다시 unsafe/참조 문제가 생기면 asmdef에서 Allow Unsafe를 켜거나, DLL 방식으로 회귀.
7) 자주 나오는 오류와 빠른 해결
•
CS0246 ‘GameFramework’ 네임스페이스 없음
→ Plugins에 DLL이 없는 상태. 빌드/복사 스크립트 동작 확인 또는 경로 오타 확인.
→ asmdef가 있으면 Override References 해제(자동 참조) 또는 참조 추가.
•
CS0227 unsafe 관련
→ DLL 방식이면 무관. 만약 소스가 Assets로 들어왔으면 asmdef Allow ‘Unsafe’ 또는 다시 DLL 방식.
•
SharpZipLib 타입을 못 찾음 / 중복 정의
→ 하나만 유지. Unity.SharpZipLib 패키지를 쓴다면 Plugins에 SharpZipLib DLL이 있으면 삭제.
•
브레이크포인트 비활성(Unbound)
→ Unity에 복사된 DLL과 PDB가 같은 빌드인지, VS Just My Code 해제 / Source Link 사용 체크.