기본형과 규칙

public async Task<Player> LoadAsync(int id, CancellationToken ct)
{
    var row  = await _db.FindAsync(id, ct);        // 대기 = 스레드 반납
    var meta = await _http.GetAsync(url, ct);      // 순차로 필요하면 이렇게
    return Map(row, meta);
}

// 서로 관계없는 작업은 동시에
var (profile, items) = (LoadProfileAsync(id, ct), LoadItemsAsync(id, ct));
await Task.WhenAll(profile, items);
return new View(profile.Result, items.Result);

// 타임아웃
using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
cts.CancelAfter(TimeSpan.FromSeconds(3));
await CallAsync(cts.Token);

• async 는 위로 전파됩니다 — 중간에서 끊지 말고 진입점까지 이어 주세요
• 반환은 Task·Task<T>. async void 는 이벤트 핸들러에서만
• 취소 토큰은 맨 아래까지 전달 — 안 그러면 취소해도 일이 계속 돕니다

터지는 세 가지 패턴

var user = GetAsync().Result;
// UI·구형 ASP.NET 에서 데드락
// 서버에서는 스레드 고갈

var user = await GetAsync();

// ② async void — 예외를 잡을 수 없어 프로세스가 죽습니다
async void Save() { await ...; }          // ✗
async Task SaveAsync() { await ...; }     // ✓

// ③ 루프 안에서 await — N번 왕복합니다
foreach (var id in ids) await LoadAsync(id, ct);        // ✗ 느림

var tasks = ids.Select(id => LoadAsync(id, ct));         // ✓ 동시에
var all   = await Task.WhenAll(tasks);

// 단, 동시 수를 제한해야 상대 서버가 죽지 않습니다
await Parallel.ForEachAsync(ids,
    new ParallelOptions { MaxDegreeOfParallelism = 10, CancellationToken = ct },
    async (id, token) => await LoadAsync(id, token));

Task 와 ValueTask

// Task — 힙에 객체 하나. 기본은 이걸로 충분합니다.
public Task<int> GetAsync() => _db.CountAsync();

// ValueTask — '대부분 이미 값이 있는' 경우의 할당 제거
public ValueTask<Item> GetItemAsync(int id)
{
    if (_cache.TryGetValue(id, out var hit))
        return new ValueTask<Item>(hit);        // 할당 0
    return new ValueTask<Item>(LoadSlowAsync(id));
}

// 오래 걸리는 CPU 작업은 스레드풀로 (UI·클라이언트 앱에서 — ASP.NET Core 요청 안에서는 이득이 없습니다)
var result = await Task.Run(() => HeavyCompute(data), ct);

// 진행률 보고
var progress = new Progress<int>(p => bar.Value = p);
await DownloadAsync(url, progress, ct);

취소 · 재시도 · 타임아웃

// 취소는 '요청'입니다 — 받은 쪽이 확인해야 멈춥니다
public async Task WorkAsync(CancellationToken ct)
{
    while (true)
    {
        ct.ThrowIfCancellationRequested();       // 협조 지점
        await StepAsync(ct);
    }
}

// 재시도 — 지수 백오프 + 지터
static async Task<T> RetryAsync<T>(Func<Task<T>> act, int max = 3)
{
    for (int i = 0; ; i++)
    {
        try { return await act(); }
        catch (Exception e) when (i < max && IsTransient(e))
        {
            var wait = TimeSpan.FromMilliseconds(
                Math.Pow(2, i) * 200 + Random.Shared.Next(100));
            await Task.Delay(wait);
        }
    }
}

경쟁 상태와 lock

private int _count;
public void Add() => _count++;      // ✗ 원자적이지 않다 (읽기→더하기→쓰기)

// ① lock — 가장 쉽고 대부분 충분
private readonly object _gate = new();
public void Add() { lock (_gate) { _count++; } }

// ② Interlocked — 단순 연산은 락 없이
Interlocked.Increment(ref _count);
Interlocked.CompareExchange(ref _state, 1, 0);   // 0이면 1로

// ③ 동시 컬렉션
private readonly ConcurrentDictionary<int, Session> _sessions = new();
_sessions.TryAdd(id, s);
_sessions.AddOrUpdate(id, s, (_, old) => old.Merge(s));

Channel — 생산자·소비자의 표준

// 게임 서버에서 '패킷 수신 → 처리' 를 잇는 가장 깔끔한 방법
var ch = Channel.CreateBounded<Packet>(new BoundedChannelOptions(10_000)
{
    FullMode = BoundedChannelFullMode.DropOldest,   // 밀리면 오래된 것부터 버림
    SingleReader = true,
});

// 생산자 — 네트워크 스레드
await ch.Writer.WriteAsync(packet, ct);

// 소비자 — 로직 스레드 하나 (락이 필요 없어집니다)
await foreach (var p in ch.Reader.ReadAllAsync(ct))
    Handle(p);

쓰는 법

// Substring 은 새 문자열을 만든다 → 할당
var head = text.Substring(0, 4);          // ✗ 힙 할당

// Span 은 '창'만 만든다 → 할당 0
ReadOnlySpan<char> span = text.AsSpan(0, 4);   // ✓

// 패킷 파싱 (게임 서버의 핵심 경로)
static bool TryParse(ReadOnlySpan<byte> buf, out Header h)
{
    if (buf.Length < 8) { h = default; return false; }
    h = new Header(
        Id:   BinaryPrimitives.ReadInt32LittleEndian(buf),
        Size: BinaryPrimitives.ReadInt32LittleEndian(buf[4..]));
    return true;
}

// 스택에 임시 버퍼 (작은 크기만!)
Span<byte> tmp = stackalloc byte[128];

규칙과 한계

• Span<T> 는 필드에 저장할 수 없습니다 — 스택 전용(ref struct)
• async 메서드에서 쓸 수 없습니다 — 그때는 Memory<T>
• stackalloc 은 루프 안에서 금지 — 스택이 넘칩니다
• 큰 버퍼는 ArrayPool<T>.Shared 에서 빌려 쓰고 돌려주세요

var buf = ArrayPool<byte>.Shared.Rent(64 * 1024);
try
{
    var n = await stream.ReadAsync(buf.AsMemory(), ct);
    Process(buf.AsSpan(0, n));
}
finally { ArrayPool<byte>.Shared.Return(buf); }   // ★ 반드시 반납

할당 없이 파싱하기 — 실전 형태

// CSV 한 줄을 문자열 하나도 안 만들고 읽기
static bool TryParseRow(ReadOnlySpan<char> line, out Row row)
{
    row = default;

    var i1 = line.IndexOf(',');
    if (i1 < 0) return false;
    var i2 = line[(i1 + 1)..].IndexOf(',');
    if (i2 < 0) return false;
    i2 += i1 + 1;

    if (!int.TryParse(line[..i1], out var id)) return false;              // 할당 0
    var name = line[(i1 + 1)..i2];                                        // 창만
    if (!decimal.TryParse(line[(i2 + 1)..], out var amount)) return false;

    row = new Row(id, name.ToString(), amount);   // 필요한 것만 문자열로
    return true;
}

// 구분자로 나누기 — Split 은 배열 + 문자열들을 만듭니다
foreach (var part in line.Split(','))            // ✗ 할당 여러 개
{ }

foreach (var range in line.AsSpan().Split(','))  // ✓ .NET 9+ — 할당 0
{
    var part = line.AsSpan()[range];
}

// 문자열 조립도 할당 없이 (길이를 아는 경우 — 8자리:7자리 = 16자)
var key = string.Create(16, (roomId, slot), static (dst, s) =>
{
    s.roomId.TryFormat(dst, out var w, "D8");     // 00001234
    dst[w] = ':';
    s.slot.TryFormat(dst[(w + 1)..], out _, "D7"); // 길이가 모자라면 남은 칸이 '\0' 으로 남습니다
});

여기서 실수합니다

// ✗ ① stackalloc 을 루프 안에서 — 스택이 쌓여 넘칩니다
for (var i = 0; i < 10000; i++)
{
    Span<byte> buf = stackalloc byte[1024];   // 스택 오버플로
}
// ✓ 루프 밖에서 한 번, 또는 ArrayPool 로
Span<byte> buf = stackalloc byte[1024];
for (var i = 0; i < 10000; i++) { buf.Clear(); /* ... */ }

// ✗ ② 크기를 입력에서 받아 stackalloc — 공격 지점이 됩니다
Span<byte> b = stackalloc byte[header.Length];       // 위험
// ✓ 상한을 두고 넘으면 풀에서
byte[]? rented = null;
Span<byte> b2 = header.Length <= 256
    ? stackalloc byte[256]
    : (rented = ArrayPool<byte>.Shared.Rent(header.Length));
try { /* 사용 */ }
finally { if (rented is not null) ArrayPool<byte>.Shared.Return(rented); }

// ✗ ③ 반납한 배열을 계속 씀 — 다른 곳이 그 배열을 빌려 갑니다
var arr = ArrayPool<byte>.Shared.Rent(1024);
ArrayPool<byte>.Shared.Return(arr);
Process(arr);                                  // 내용이 이미 바뀌었을 수 있습니다

// ✗ ④ Rent 는 "요청한 크기 이상"을 줍니다 — Length 를 믿지 마세요
var a = ArrayPool<byte>.Shared.Rent(100);
// a.Length 는 128 일 수 있습니다
Process(a.AsSpan(0, 100));                     // ✓ 실제 크기를 직접 잘라 쓰기

// ✗ ⑤ 민감 데이터를 담았다면 반납 전에 지우기
ArrayPool<byte>.Shared.Return(a, clearArray: true);

어디서 몰래 할당되는가

void Update()
{
    // ① 문자열 — 매 프레임 새 객체
    label.text = "HP " + hp;                     // ✗

    // ② 박싱 — 값 타입이 object 로 변할 때
    object o = 3;                                // ✗
    Debug.Log(string.Format("{0}", hp));         // ✗ 박싱

    // ③ 람다가 바깥 변수를 잡을 때(클로저)
    list.ForEach(x => x.Add(offset));            // ✗ offset 캡처

    // ④ LINQ · foreach on interface
    var alive = enemies.Where(e => e.Hp > 0);    // ✗ 반복자 객체

    // ⑤ params · 배열
    Log("a", "b");                               // params → 배열 생성
}

고치는 법

// ① 값이 바뀔 때만 갱신 + 캐시
private int _shownHp = -1;
void Update()
{
    if (_shownHp == hp) return;
    _shownHp = hp;
    label.SetText("HP {0}", hp);      // TMP 의 할당 없는 API
}

// ② 재사용 버퍼
private readonly Collider[] _buffer = new Collider[32];
int n = Physics.OverlapSphereNonAlloc(pos, r, _buffer);   // NonAlloc 계열 — 앞 n 개만 유효

// ③ 구조체 + 정적 람다
list.ForEach(static x => x.Reset());   // 캡처 없음을 컴파일러가 보장

// ④ 오브젝트 풀
var bullet = _pool.Rent();
_pool.Return(bullet);

기본형

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSingleton<IClock, SystemClock>();      // 앱 전체 1개
builder.Services.AddScoped<IUserRepository, UserRepo>();   // 요청마다 1개
builder.Services.AddTransient<IMailer, Mailer>();          // 쓸 때마다 새로
builder.Services.AddHttpClient<IPayApi, PayApi>();

// 설정을 타입으로 받기
builder.Services.Configure<GameOptions>(
    builder.Configuration.GetSection("Game"));

var app = builder.Build();

// 생성자로 받기만 하면 됩니다
public sealed class MatchService(
    IUserRepository users,
    IOptions<GameOptions> opt,
    ILogger<MatchService> log)
{
    private readonly int _maxParty = opt.Value.MaxParty;
}

수명을 틀리면 생기는 일

수명(Lifetime) 세 가지 — 잘못 고르면 버그가 됩니다

DI 가 있으면 테스트가 이렇게 됩니다

// 결제 서비스 — 외부 PG 사를 인터페이스 뒤로
public class OrderService(IPayGateway pay, IClock clock)
{
    public async Task<Order> Checkout(Cart cart)
    {
        var paid = await pay.ChargeAsync(cart.Total);
        return new Order(cart, paid.TxId, clock.Now);
    }
}

// 테스트 — 진짜 결제 없이 실패 상황까지 재현
var fakePay  = new FakeGateway { FailWith = "한도 초과" };
var fixedNow = new FixedClock(new DateTime(2026, 1, 1));
var svc = new OrderService(fakePay, fixedNow);

await Assert.ThrowsAsync<PaymentException>(
    () => svc.Checkout(cart));

System.Text.Json

var opt = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    Converters = { new JsonStringEnumConverter() },
};

var json = JsonSerializer.Serialize(dto, opt);
var back = JsonSerializer.Deserialize<Dto>(json, opt);

// 소스 제너레이터 — 리플렉션 없이 (AOT · 성능)
[JsonSerializable(typeof(Dto))]
internal partial class AppJson : JsonSerializerContext { }

var fast = JsonSerializer.Serialize(dto, AppJson.Default.Dto);

게임 패킷은 바이너리로

// MessagePack — 속성만 붙이면 됩니다
[MessagePackObject]
public class MovePacket
{
    [Key(0)] public int   Id { get; set; }
    [Key(1)] public float X  { get; set; }
    [Key(2)] public float Y  { get; set; }
}

var bytes = MessagePackSerializer.Serialize(p);   // 20바이트 수준
var p2    = MessagePackSerializer.Deserialize<MovePacket>(bytes);

리플렉션

// 타입 정보를 런타임에 읽는다
var t = typeof(Player);
foreach (var p in t.GetProperties())
    Console.WriteLine($"{p.Name} : {p.PropertyType.Name}");

// 속성(Attribute) 으로 표시하고 찾아 쓰기
[AttributeUsage(AttributeTargets.Method)]
public sealed class CommandAttribute(string name) : Attribute
{
    public string Name { get; } = name;
}

var handlers = typeof(Program).Assembly.GetTypes()
    .SelectMany(t => t.GetMethods())
    .Where(m => m.GetCustomAttribute<CommandAttribute>() is not null);

소스 제너레이터 — 빌드 때 코드를 만든다

// 쓰는 쪽은 partial 하나면 됩니다
public partial class Player
{
    [GeneratedRegex(@"^[a-zA-Z0-9_]{3,16}$")]
    private static partial Regex NameRule();     // 컴파일 시점 생성

    public bool IsValidName(string n) => NameRule().IsMatch(n);
}

// 로깅도 같은 방식 — 문자열 포맷을 미리 만들어 둡니다
public static partial class Log
{
    [LoggerMessage(Level = LogLevel.Warning,
                   Message = "매칭 실패 {RoomId} 사유={Reason}")]
    public static partial void MatchFailed(ILogger l, int roomId, string reason);
}

세 가지를 실제로 바꿔 보기

// ① 정규식 — new Regex 는 매번 파싱·컴파일합니다
// ✗
public bool IsValid(string n) => new Regex(@"^\w{3,16}$").IsMatch(n);
// ✓ 빌드 시점에 최적화된 코드가 생성됩니다
[GeneratedRegex(@"^\w{3,16}$", RegexOptions.CultureInvariant)]
private static partial Regex NameRule();

// ② 로깅 — 보간 문자열은 레벨이 꺼져 있어도 문자열을 만듭니다
// ✗ Debug 가 꺼져 있어도 ToString() 이 전부 실행됩니다
_log.LogDebug($"매칭 {roomId} {player.Name} {DateTime.UtcNow}");
// ✓ 실제로 찍힐 때만 포맷됩니다 + 구조화 로그로 검색 가능
[LoggerMessage(Level = LogLevel.Debug, Message = "매칭 {RoomId} {Player}")]
public static partial void Matched(ILogger l, int roomId, string player);

// ③ JSON — 기본 직렬화는 리플렉션으로 타입을 훑습니다
[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
[JsonSerializable(typeof(PlayerDto))]
[JsonSerializable(typeof(List<ItemDto>))]
internal partial class AppJson : JsonSerializerContext;

var s = JsonSerializer.Serialize(dto, AppJson.Default.PlayerDto);

// ASP.NET Core 전역 적용
builder.Services.ConfigureHttpJsonOptions(o =>
    o.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJson.Default));

리플렉션을 꼭 써야 한다면

// 시작할 때 한 번만 훑고 결과를 캐시합니다 — 매 호출 조회는 금물
public static class CommandRegistry
{
    private static readonly FrozenDictionary<string, Action<string[]>> Map =
        BuildMap();

    private static FrozenDictionary<string, Action<string[]>> BuildMap()
    {
        var d = new Dictionary<string, Action<string[]>>(StringComparer.OrdinalIgnoreCase);
        foreach (var m in typeof(Commands).GetMethods(
                     BindingFlags.Public | BindingFlags.Static))
        {
            if (m.GetCustomAttribute<CommandAttribute>() is not { } attr) continue;
            // ★ 델리게이트로 만들어 두면 이후 호출은 리플렉션이 아닙니다
            var fn = m.CreateDelegate<Action<string[]>>();
            d[attr.Name] = fn;
        }
        return d.ToFrozenDictionary();     // .NET 8+ — 읽기 전용에 최적화
    }

    public static bool TryRun(string name, string[] args)
    {
        if (!Map.TryGetValue(name, out var fn)) return false;
        fn(args);                          // 일반 델리게이트 호출 속도
        return true;
    }
}

DllImport

using System.Runtime.InteropServices;

internal static partial class Native
{
    // .NET 7+ — 소스 제너레이터 방식(빠르고 AOT 안전)
    [LibraryImport("user32.dll", StringMarshalling = StringMarshalling.Utf16)]
    [return: MarshalAs(UnmanagedType.Bool)]
    internal static partial bool MessageBeep(uint type);

    [LibraryImport("mylib", EntryPoint = "compute")]
    internal static partial int Compute(
        ReadOnlySpan<float> input, Span<float> output, int len);
}

지켜야 할 것

• 구조체 레이아웃을 [StructLayout(LayoutKind.Sequential)] 로 고정
• 포인터로 넘길 배열은 고정(fixed)하거나 Span 사용 — GC 가 옮기면 터집니다
• 네이티브가 준 메모리는 누가 해제하는지 문서로 남기세요
• 플랫폼별 바이너리(.dll·.so·.dylib)를 전부 배포해야 합니다

안전하게 감싸는 형태

// ① 핸들은 SafeHandle 로 — Dispose 를 잊어도 파이널라이저가 해제합니다
internal sealed class AudioHandle() : SafeHandleZeroOrMinusOneIsInvalid(true)
{
    protected override bool ReleaseHandle()
    {
        Native.AudioClose(handle);
        return true;
    }
}

internal static partial class Native
{
    [LibraryImport("audio", StringMarshalling = StringMarshalling.Utf8)]
    internal static partial AudioHandle AudioOpen(string device);

    [LibraryImport("audio")]
    internal static partial void AudioClose(nint h);

    // ② 배열은 Span 으로 — 복사도 고정(pinning)도 필요 없습니다
    [LibraryImport("audio")]
    internal static partial int AudioMix(
        ReadOnlySpan<float> input, Span<float> output, int frames);
}

// ③ 구조체는 레이아웃을 못 박습니다
[StructLayout(LayoutKind.Sequential, Pack = 4)]
internal struct Vec3
{
    public float X, Y, Z;
}

// ④ 콜백은 정적 메서드 + 함수 포인터로 (GC 수거 걱정이 없습니다)
[UnmanagedCallersOnly(CallConvs = [typeof(CallConvCdecl)])]
private static void OnFrame(nint ctx, int frames) { /* ... */ }

unsafe
{
    Native.AudioSetCallback(&OnFrame);
}

배포와 진단

<!-- 플랫폼별 네이티브 바이너리를 전부 넣어야 합니다 -->
<ItemGroup>
  <None Include="native/win-x64/audio.dll">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    <Link>runtimes/win-x64/native/audio.dll</Link>
  </None>
  <None Include="native/linux-x64/libaudio.so">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    <Link>runtimes/linux-x64/native/libaudio.so</Link>
  </None>
</ItemGroup>

// 이름이 플랫폼마다 다르면 직접 해석기를 등록합니다
static Native()
{
    NativeLibrary.SetDllImportResolver(typeof(Native).Assembly, (name, asm, path) =>
    {
        if (name != "audio") return nint.Zero;
        var file = OperatingSystem.IsWindows() ? "audio.dll"
                 : OperatingSystem.IsMacOS()   ? "libaudio.dylib"
                 :                               "libaudio.so";
        return NativeLibrary.Load(file, asm, path);
    });
}

벤치마크 작성

dotnet add package BenchmarkDotNet
dotnet run -c Release          # ★ 반드시 Release

[MemoryDiagnoser]                       // 할당량도 함께 측정
[SimpleJob(RuntimeMoniker.Net100)]
public class ParseBench
{
    private string _line = "12,34,56";

    [Benchmark(Baseline = true)]
    public int[] Split() => _line.Split(',').Select(int.Parse).ToArray();

    [Benchmark]
    public int SpanParse()
    {
        var s = _line.AsSpan(); int sum = 0;
        foreach (var range in s.Split(','))
            sum += int.Parse(s[range]);
        return sum;
    }
}

읽는 법 · 함정

| Method    |      Mean | Ratio | Allocated |
|---------- |----------:|------:|----------:|
| Split     | 210.4 ns  |  1.00 |     264 B |
| SpanParse |  38.7 ns  |  0.18 |       0 B |   ← 5배 · 할당 0

• Allocated 열을 먼저 보세요 — 게임에서는 이게 프레임 튐입니다
• Mean 차이가 20% 이내면 의미 없는 경우가 많습니다(측정 오차·환경)
• 실제 데이터 크기로 재세요. 10개와 10만 개는 결과가 뒤집힙니다
• Debug 빌드 측정은 전부 무효입니다

솔루션 나누기

MyGame.sln
  src/
    MyGame.Domain/          도메인 규칙 — 아무것도 참조하지 않는다
      Player.cs  Item.cs  IInventory.cs
    MyGame.Application/     유스케이스 — Domain 만 참조
      BuyItemHandler.cs
    MyGame.Infrastructure/  DB·HTTP·Redis 구현 — Application 참조
      EfInventory.cs  RedisRanking.cs
    MyGame.Api/             진입점 — 전부 조립
      Program.cs
  tests/
    MyGame.Domain.Tests/
    MyGame.Api.IntegrationTests/

규칙을 코드로 강제하기

// NetArchTest — 의존 방향이 깨지면 테스트가 실패합니다
[Fact]
public void 도메인은_인프라를_모른다()
{
    var result = Types.InAssembly(typeof(Player).Assembly)
        .Should().NotHaveDependencyOn("MyGame.Infrastructure")
        .GetResult();

    Assert.True(result.IsSuccessful);
}

<!-- Directory.Build.props — 모든 프로젝트에 공통 설정 -->
<Project>
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <LangVersion>latest</LangVersion>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
    <AnalysisLevel>latest-recommended</AnalysisLevel>
  </PropertyGroup>
</Project>

언어 · 런타임

• DateTime.Now 대신 DateTimeOffset.UtcNow — 서버는 UTC 로 저장하고 표시할 때만 변환
• new Random() 을 반복 생성 — 같은 값이 나옵니다. Random.Shared
• IDisposable 을 안 닫음 — using 을 습관으로
• 예외를 흐름 제어로 사용 — 느리고 의도가 흐려집니다
• == 로 문자열 비교 시 문화권 이슈 — StringComparison 명시
• float 비교를 == 로 — 오차 범위로 비교하세요

서버 · 게임

• 클라이언트를 믿는 것 — 좌표·데미지·재화는 서버가 계산합니다(🌐 게임 서버 탭)
• 동기 API 를 서버에서 호출 — .Result 하나로 처리량이 무너집니다
• Update 안의 GetComponent·Find — Awake 에서 캐시
• 로그를 문자열로 조립 — 구조적 로깅(log.Info("x {A}", a))
• 설정을 코드에 하드코딩 — 환경별로 갈라지는 순간 사고가 납니다
• 테스트 없는 리팩터링 — 성능 개선일수록 동작 보장이 먼저입니다

Parallel.For / ForEach

// CPU 를 쓰는 무거운 계산을 코어 수만큼 나눕니다
Parallel.For(0, maps.Length, i =>
{
    maps[i] = GenerateChunk(i);        // 각자 다른 칸에 쓰므로 안전
});

Parallel.ForEach(images, new ParallelOptions
{
    MaxDegreeOfParallelism = Environment.ProcessorCount,
    CancellationToken = ct,            // ★ 취소 연동 — 없으면 끝까지 돕니다
},
img => Resize(img));

// IO 가 섞인 작업은 ForEachAsync (a01 에서 본 그것)
await Parallel.ForEachAsync(urls,
    new ParallelOptions { MaxDegreeOfParallelism = 8, CancellationToken = ct },
    async (url, token) => await DownloadAsync(url, token));

// 취소되면 OperationCanceledException 으로 빠져나옵니다
try { Parallel.ForEach(...); }
catch (OperationCanceledException) { /* 정상 취소 경로 */ }

PLINQ — LINQ 에 AsParallel 한 줄

// 항목당 계산이 무거울 때 — 체인 그대로 병렬이 됩니다
var results = candidates
    .AsParallel()
    .WithDegreeOfParallelism(Environment.ProcessorCount)
    .WithCancellation(ct)
    .Where(c => HeavyScore(c) > threshold)   // 여기가 무거워야 이득
    .Select(c => Transform(c))
    .ToList();

// ★ 순서가 필요하면 명시해야 합니다 — 기본은 순서 보장 없음
var ordered = xs.AsParallel().AsOrdered().Select(Heavy).ToList();

// 집계는 병렬 전용 연산자가 안전합니다
var total = xs.AsParallel().Sum(x => Heavy(x));

// 결과를 나오는 대로 소비 — 전부 끝나길 안 기다립니다
foreach (var r in xs.AsParallel().Select(Heavy))
    Consume(r);   // 순서는 뒤섞여 도착합니다

Regex 기본 · [GeneratedRegex]

using System.Text.RegularExpressions;

// ✗ 호출마다 new Regex — 파싱·컴파일을 매번 반복합니다
bool Bad(string s) => new Regex(@"^\d+$").IsMatch(s);

// ✓ .NET 7+ 표준: 소스 제너레이터 — 빌드 시점에 코드 생성
public static partial class Patterns
{
    [GeneratedRegex(@"^[가-힣a-zA-Z0-9]{2,12}$")]
    public static partial Regex Nickname();

    [GeneratedRegex(@"^(?<ip>\S+) \S+ \S+ \[(?<time>[^\]]+)\] " +
                    @"""(?<method>\S+) (?<path>\S+)[^""]*"" (?<status>\d{3})")]
    public static partial Regex AccessLog();
}

Patterns.Nickname().IsMatch(input);        // 할당·컴파일 비용 없음

// 그룹 이름으로 꺼내기
var m = Patterns.AccessLog().Match(line);
if (m.Success)
    Record(m.Groups["path"].Value, int.Parse(m.Groups["status"].Value));

타임아웃 — ReDoS 를 막는 한 줄

// 이 패턴은 정상 입력에선 멀쩡하다가
// "aaaaaaaaaaaaaaaaaaaaaaaaaaaa!" 같은 입력에서
// 되추적(backtracking)이 폭발해 CPU 100% 로 멈춥니다
var evil = new Regex(@"^(a+)+$");

// ✓ 사용자 입력을 만지는 정규식에는 반드시 시간 제한
var safe = new Regex(@"^(a+)+$", RegexOptions.None,
                     TimeSpan.FromMilliseconds(100));
try { safe.IsMatch(userInput); }
catch (RegexMatchTimeoutException) { return BadRequest(); }

// ✓ 더 근본적인 해법 — 되추적 자체를 끕니다 (.NET 7+)
var nb = new Regex(@"^(a+)+$", RegexOptions.NonBacktracking);
// 실행 시간이 입력 길이에 비례하도록 보장됩니다

// [GeneratedRegex] 에도 지정할 수 있습니다
[GeneratedRegex(@"^\w+@\w+\.\w+$", RegexOptions.NonBacktracking)]
public static partial Regex SimpleEmail();

실무 예제 — 닉네임 검증 · 로그 집계

// 닉네임: 한글·영문·숫자 2~12자, 정규식 + 규칙 검사 조합
public static Result Validate(string nick)
{
    if (!Patterns.Nickname().IsMatch(nick))
        return Result.Fail("2~12자, 한글·영문·숫자만 가능합니다");
    if (BannedWords.Any(w => nick.Contains(w, StringComparison.OrdinalIgnoreCase)))
        return Result.Fail("사용할 수 없는 단어가 포함되어 있습니다");
    return Result.Ok;
}

// 로그 파일에서 5xx 경로 집계 — 파싱은 정규식, 집계는 LINQ
var top = File.ReadLines(path)                  // 한 줄씩 (전체 로드 X)
    .Select(l => Patterns.AccessLog().Match(l))
    .Where(m => m.Success && m.Groups["status"].Value[0] == '5')
    .GroupBy(m => m.Groups["path"].Value)
    .OrderByDescending(g => g.Count())
    .Take(10);

문자열 조립 — StringBuilder 너머

// 반복 조립의 기본은 StringBuilder (기초 c03 · a10 벤치마크 참고)
var sb = new StringBuilder(capacity: 4096);   // ★ 크기를 알면 미리
foreach (var e in entries)
    sb.Append(e.Time).Append('\t').Append(e.Msg).AppendLine();

// 최종 길이를 아는 뜨거운 경로 — string.Create 로 할당 1회
// 예: 8자리 초대 코드 수만 개 생성
static string InviteCode(char[] alphabet, Random rng)
    => string.Create(8, (alphabet, rng), (span, s) =>
    {
        for (int i = 0; i < span.Length; i++)
            span[i] = s.alphabet[s.rng.Next(s.alphabet.Length)];
    });
// 중간 배열·StringBuilder 없이 최종 문자열 버퍼에 직접 씁니다

// 보간 문자열도 조건부라면 지연시키세요
_log.LogDebug("state {State} tick {Tick}", state, tick);
// ✗ $"..." 로 만들면 로그 레벨이 꺼져 있어도 조립 비용을 냅니다

해시(SHA-256) · HMAC 서명

using System.Security.Cryptography;
using System.Text;

// 해시 — 내용의 지문. 파일 무결성·중복 검사·캐시 키
byte[] hash = SHA256.HashData(File.ReadAllBytes(path));   // static 한 줄
string hex  = Convert.ToHexString(hash);                  // "A3F2…"

// 대용량 파일은 스트림으로
await using var fs = File.OpenRead(path);
var h2 = await SHA256.HashDataAsync(fs, ct);

// HMAC — "비밀 키를 아는 쪽이 만들었다"는 서명.
// 웹훅 검증·클라이언트 요청 위조 방지의 표준입니다
static bool VerifyWebhook(string body, string signatureHex, byte[] secret)
{
    var expected = HMACSHA256.HashData(secret, Encoding.UTF8.GetBytes(body));
    var actual   = Convert.FromHexString(signatureHex);
    // ★ 일반 비교(SequenceEqual)는 틀린 위치에서 일찍 끝나
    //   시간 차이로 서명이 새는 타이밍 공격에 노출됩니다
    return CryptographicOperations.FixedTimeEquals(expected, actual);
}

// 게임 예: 결제 영수증·랭킹 제출에 서버 발급 HMAC 를 붙여
// 클라이언트가 값을 조작했는지 서버에서 검증합니다

대칭 암호화 — AES-GCM

// 암호화 + 변조 감지를 한 번에 하는 인증 암호화(AEAD)
public static byte[] Encrypt(byte[] plain, byte[] key)
{
    var nonce = RandomNumberGenerator.GetBytes(AesGcm.NonceByteSizes.MaxSize);
    var cipher = new byte[plain.Length];
    var tag    = new byte[AesGcm.TagByteSizes.MaxSize];

    using var aes = new AesGcm(key, tag.Length);
    aes.Encrypt(nonce, plain, cipher, tag);

    // nonce ‖ tag ‖ cipher 를 붙여 저장 — 셋 다 비밀이 아닙니다
    return [.. nonce, .. tag, .. cipher];
}

public static byte[] Decrypt(byte[] blob, byte[] key)
{
    var nonce  = blob.AsSpan(0, 12);
    var tag    = blob.AsSpan(12, 16);
    var cipher = blob.AsSpan(28);
    var plain  = new byte[cipher.Length];
    using var aes = new AesGcm(key, tag.Length);
    aes.Decrypt(nonce, cipher, tag, plain);   // 변조됐으면 여기서 예외
    return plain;
}

비밀번호 — 해시가 아니라 KDF

// 비밀번호는 "느리게" 해시해야 합니다 — 무차별 대입을 비싸게
// SHA256 은 초당 수십억 번 계산되므로 자격이 없습니다

// 표준 라이브러리만으로: PBKDF2
const int Iterations = 600_000;              // OWASP 권고 수준
public static (byte[] Salt, byte[] Hash) HashPassword(string pw)
{
    var salt = RandomNumberGenerator.GetBytes(16);   // 사용자마다 다르게
    var hash = Rfc2898DeriveBytes.Pbkdf2(
        pw, salt, Iterations, HashAlgorithmName.SHA256, outputLength: 32);
    return (salt, hash);
}

public static bool Verify(string pw, byte[] salt, byte[] stored)
{
    var hash = Rfc2898DeriveBytes.Pbkdf2(
        pw, salt, Iterations, HashAlgorithmName.SHA256, 32);
    return CryptographicOperations.FixedTimeEquals(hash, stored);
}

// ASP.NET Core Identity 를 쓴다면 이미 내장되어 있습니다
// (PasswordHasher<T>) — 직접 만들 이유가 없습니다.
// BCrypt.Net-Next · Argon2 패키지도 검증된 선택지입니다

난수 — 뽑기(가챠)에 Random 을 쓰면

// Random / Random.Shared — 예측 가능한 의사 난수
var dmg = damage * Random.Shared.NextSingle();   // ✓ 연출·흔들림·AI 는 OK

// ✗ 보상·뽑기·쿠폰·토큰에 쓰면 안 됩니다
//   시드를 알면(또는 출력 몇 개를 보면) 다음 값이 예측됩니다

// ✓ 결과가 돈이 되는 곳은 암호학적 난수
int roll = RandomNumberGenerator.GetInt32(0, 10000);   // 편향 없는 정수
if (roll < 30) GrantSSR();                             // 0.3%

// 세션 토큰·쿠폰 코드
var token = Convert.ToBase64String(RandomNumberGenerator.GetBytes(32));

// 셔플도 마찬가지 — 카드 게임 서버라면
for (int i = deck.Count - 1; i > 0; i--)
{
    int j = RandomNumberGenerator.GetInt32(i + 1);
    (deck[i], deck[j]) = (deck[j], deck[i]);
}

설치 순서

• Unity Hub 설치 → 여기서 에디터 버전을 깝니다
• LTS 버전을 고르세요 — 최신 베타는 플러그인이 안 붙습니다
• 모듈에서 빌드 대상 체크(Android · iOS · WebGL · Windows)
• 에디터는 Rider 또는 VS Code + C# Dev Kit

템플릿 고르기
  2D (Built-in)      가장 단순 · 첫 게임에 좋음
  Universal 3D (URP) 모바일·PC 대부분 ★ 기본값으로 권장
  HDRP               고사양 PC·콘솔 전용
  3D (Built-in)      옛 프로젝트 유지보수용

창 다섯 개

따라 하기 — 굴러가는 공 하나

1. Hierarchy 우클릭 → 3D Object → Plane   (바닥)
2. Hierarchy 우클릭 → 3D Object → Sphere  (공)
3. Sphere 를 클릭 → Inspector 아래 [Add Component]
   → Rigidbody 추가                        (중력을 받게)
4. Sphere 의 Position Y 를 5 로            (공중에 띄우기)
5. ▶ 재생 → 공이 떨어져 바닥에 멈추면 성공

코드 한 줄 없이 물리가 도는 장면이 만들어졌습니다. Unity 개발은 이 위에 스크립트라는 부품을 얹는 일입니다.

// 6. Project 우클릭 → Create → C# Script → "Roller"
// 7. 이 파일을 Sphere 로 드래그 (= 부품으로 붙이기)
using UnityEngine;

public class Roller : MonoBehaviour
{
    [SerializeField] private float power = 10f;
    private Rigidbody _rb;
    private Vector3 _input;

    void Awake() => _rb = GetComponent<Rigidbody>();   // 한 번만 찾아 둔다

    void Update()                                // 입력은 Update 에서 읽고
    {
        float h = Input.GetAxis("Horizontal");   // A·D / ←→
        float v = Input.GetAxis("Vertical");     // W·S / ↑↓
        _input = new Vector3(h, 0, v);
    }

    void FixedUpdate() => _rb.AddForce(_input * power);   // 힘은 물리 주기에
}

손이 빨라지는 필수 단축키

코드에서 다루기

using UnityEngine;

public class Player : MonoBehaviour       // ← 컴포넌트가 되려면 상속
{
    // Inspector 에 노출 (public 대신 이걸 권장 — 캡슐화 유지)
    [SerializeField] private float speed = 5f;
    [SerializeField] private Transform muzzle;

    private Rigidbody _rb;

    void Awake()
    {
        // ★ 매 프레임 찾지 말고 한 번만 캐시
        _rb = GetComponent<Rigidbody>();
    }

    void Update()
    {
        var h = Input.GetAxis("Horizontal");
        transform.Translate(Vector3.right * h * speed * Time.deltaTime);
    }
}

찾기 · 만들기 · 지우기

// 자신·자식·부모에서 찾기
var col = GetComponent<Collider>();
var gun = GetComponentInChildren<Gun>();
var mgr = GetComponentInParent<RoomManager>();

// 씬 전체에서 찾기 — 느립니다. 시작할 때 한 번만.
var spawner = FindFirstObjectByType<Spawner>();

// 만들기 · 지우기
var go = Instantiate(bulletPrefab, muzzle.position, muzzle.rotation);
Destroy(go, 3f);                 // 3초 뒤 파괴
gameObject.SetActive(false);     // 끄기(파괴보다 훨씬 쌉니다)

// 태그 · 레이어
if (other.CompareTag("Enemy")) { }        // == "Enemy" 보다 빠름

Unity 식 설계 — 기능 하나 = 컴포넌트 하나

Character
 └ Player : Character
    └ FlyingPlayer : Player
       └ ...  // 조합이 늘수록 폭발

Player   = Mover + Health + Shooter
Enemy    = Mover + Health + ChaseAI
Turret   =         Health + Shooter
// 붙였다 뗐다로 조합 완성

// Health 는 "체력이 필요한 모든 것"에 그대로 재사용
public class Health : MonoBehaviour
{
    [SerializeField] private int max = 100;
    public int Current { get; private set; }
    public event System.Action<int> OnDamaged;
    public event System.Action OnDied;

    void Awake() => Current = max;

    public void TakeDamage(int dmg)
    {
        Current = Mathf.Max(0, Current - dmg);
        OnDamaged?.Invoke(Current);
        if (Current == 0) OnDied?.Invoke();
    }
}
// Player 도 Enemy 도 상자도 전부 이 한 부품을 씁니다

자주 붙이는 내장 컴포넌트 지도

호출 순서

Awake()          오브젝트 생성 직후 (자기 초기화 · 캐시)
OnEnable()       활성화될 때마다 (이벤트 구독)
Start()          첫 프레임 직전 (다른 오브젝트 참조 OK)
  ↓ 매 프레임
FixedUpdate()    물리 주기 (기본 0.02초) ← Rigidbody 는 여기서
Update()         화면 주기 (프레임마다) ← 입력·로직
LateUpdate()     Update 끝난 뒤     ← 카메라 추적
  ↓
OnDisable()      비활성화 (이벤트 해지)
OnDestroy()      파괴 직전 (정리)

Update 세 형제 구분

void Update()
{
    // ★ 프레임마다 시간이 다르므로 deltaTime 을 곱한다
    transform.position += dir * speed * Time.deltaTime;

    if (Input.GetKeyDown(KeyCode.Space)) _jump = true;   // 입력은 Update
}

void FixedUpdate()
{
    if (_jump) { _rb.AddForce(Vector3.up * power, ForceMode.Impulse); _jump = false; }
    _rb.MovePosition(_rb.position + dir * speed * Time.fixedDeltaTime);
}

void LateUpdate()
{
    cam.position = target.position + offset;   // 대상이 다 움직인 뒤 따라간다
}

기본 형태

// "기다렸다가 이어서" 를 함수 하나로 씁니다
IEnumerator RespawnRoutine()
{
    ShowDeathEffect();
    yield return new WaitForSeconds(3f);     // 3초 대기
    transform.position = spawnPoint.position;
    yield return null;                       // 한 프레임 대기
    SetInvincible(2f);
}

void Die() => StartCoroutine(RespawnRoutine());

// 자주 쓰는 yield 들
yield return null;                           // 다음 프레임
yield return new WaitForSeconds(1f);         // 초 단위
yield return new WaitForFixedUpdate();       // 다음 물리 틱
yield return new WaitUntil(() => loaded);    // 조건이 참이 될 때까지
yield return StartCoroutine(Other());        // 다른 코루틴이 끝날 때까지

함정과 대안

// 반복 타이머 — Update 에서 시간 더하기보다 깔끔
IEnumerator SpawnLoop()
{
    var wait = new WaitForSeconds(2f);   // ★ 재사용 (매번 new 는 GC)
    while (enabled)
    {
        Spawn();
        yield return wait;
    }
}

// 중단이 필요하면 핸들을 잡아 두세요
Coroutine _loop;
void OnEnable()  => _loop = StartCoroutine(SpawnLoop());
void OnDisable() { if (_loop != null) StopCoroutine(_loop); }

이동과 회전

// 위치
transform.position      = new Vector3(0, 1, 0);   // 월드 기준
transform.localPosition = Vector3.zero;           // 부모 기준
transform.Translate(Vector3.forward * 2f);        // 자기 방향으로

// 회전 — 각도(Euler)는 보기 편하고, 계산은 Quaternion 으로
transform.rotation = Quaternion.Euler(0, 90, 0);
transform.Rotate(Vector3.up, 90f * Time.deltaTime);
transform.LookAt(target);

// 부드럽게 회전
var want = Quaternion.LookRotation(dir);
transform.rotation = Quaternion.Slerp(transform.rotation, want, 8f * Time.deltaTime);

// 부모 자식
child.SetParent(parent, worldPositionStays: false);

자주 쓰는 벡터 계산

var to    = target.position - transform.position;
var dist  = to.magnitude;              // 거리
var dir   = to.normalized;             // 방향(길이 1)

// ★ 거리 비교는 제곱으로 (제곱근 계산을 피한다)
if (to.sqrMagnitude < range * range) Attack();

var lerp  = Vector3.Lerp(a, b, 0.5f);             // 중간값
var moved = Vector3.MoveTowards(a, b, speed * Time.deltaTime);
var dot   = Vector3.Dot(transform.forward, dir);  // 앞에 있나? (>0)
var cross = Vector3.Cross(a, b);                  // 수직 벡터

// 2D 라면 z 를 무시하고 Vector2 를 쓰세요

2D 게임이라면

// 2D 는 z 를 안 쓰고, 회전은 z축 하나만 씁니다
transform.position = new Vector2(3, 1);        // z=0 으로 들어감

// 스프라이트 좌우 반전 — 회전 대신 flipX
GetComponent<SpriteRenderer>().flipX = dir.x < 0;

// 마우스 방향으로 회전 (탑다운 슈터)
Vector2 to = mouseWorld - (Vector2)transform.position;
float deg = Mathf.Atan2(to.y, to.x) * Mathf.Rad2Deg;
transform.rotation = Quaternion.Euler(0, 0, deg - 90f);

좌표 변환 — 화면 ↔ 월드

// 마우스 클릭 지점을 월드 좌표로 (2D)
Vector2 world = Camera.main.ScreenToWorldPoint(Input.mousePosition);

// 월드 좌표를 화면 좌표로 — 머리 위 체력바·이름표
Vector3 screen = Camera.main.WorldToScreenPoint(enemy.position);
nameTag.position = screen;
if (screen.z < 0) nameTag.gameObject.SetActive(false);  // 뒤에 있으면 숨김

// 부모 기준 ↔ 월드 기준
Vector3 w = transform.TransformPoint(localOffset);   // 로컬 → 월드
Vector3 l = transform.InverseTransformPoint(worldPos); // 월드 → 로컬

옛 방식 (Input Manager)

// 배우기 쉽고 예제가 많지만, 패드·터치 대응이 번거롭습니다
float h = Input.GetAxis("Horizontal");        // -1 ~ 1 (부드럽게)
float raw = Input.GetAxisRaw("Horizontal");   // -1 / 0 / 1 (즉시)

if (Input.GetKeyDown(KeyCode.Space)) Jump();  // 누른 순간
if (Input.GetKey(KeyCode.LeftShift)) Run();   // 누르고 있는 동안
if (Input.GetMouseButtonDown(0)) Fire();

// 마우스로 화면 좌표 → 월드
var ray = Camera.main.ScreenPointToRay(Input.mousePosition);
if (Physics.Raycast(ray, out var hit)) Move(hit.point);

새 Input System (권장)

# Package Manager → Input System 설치 후 재시작
# Project Settings → Player → Active Input Handling: Both

using UnityEngine.InputSystem;

public class PlayerInputHandler : MonoBehaviour
{
    private InputAction _move, _jump;

    void Awake()
    {
        var map = new InputActionMap("Player");
        _move = map.AddAction("Move", binding: "<Gamepad>/leftStick");
        _move.AddCompositeBinding("2DVector")
             .With("Up", "<Keyboard>/w").With("Down", "<Keyboard>/s")
             .With("Left", "<Keyboard>/a").With("Right", "<Keyboard>/d");
        _jump = map.AddAction("Jump", binding: "<Keyboard>/space");
        map.Enable();
    }

    void Update()
    {
        var v = _move.ReadValue<Vector2>();
        if (_jump.WasPressedThisFrame()) Jump();
    }
}

모바일 터치

using UnityEngine.InputSystem;
using UnityEngine.InputSystem.EnhancedTouch;
using Touch = UnityEngine.InputSystem.EnhancedTouch.Touch;

void OnEnable()  => EnhancedTouchSupport.Enable();
void OnDisable() => EnhancedTouchSupport.Disable();

void Update()
{
    foreach (var t in Touch.activeTouches)
    {
        if (t.began)                    OnTap(t.screenPosition);
        if (t.inProgress)               OnDrag(t.delta);
    }

    // 핀치 줌 — 두 손가락 거리 변화
    if (Touch.activeTouches.Count == 2)
    {
        var a = Touch.activeTouches[0];
        var b = Touch.activeTouches[1];
        float now  = Vector2.Distance(a.screenPosition, b.screenPosition);
        float prev = Vector2.Distance(a.screenPosition - a.delta,
                                      b.screenPosition - b.delta);
        Zoom((now - prev) * 0.01f);
    }
}

"UI 를 뚫고 게임이 클릭되는" 문제

일시정지 버튼을 눌렀는데 그 밑의 캐릭터가 공격하는 사고 — 터치 게임의 단골 버그입니다. 입력이 UI 를 통과했는지 먼저 물어보세요.

using UnityEngine.EventSystems;

bool PointerOnUI()
{
#if UNITY_EDITOR || UNITY_STANDALONE
    return EventSystem.current.IsPointerOverGameObject();
#else
    // 모바일은 터치 id 를 넘겨야 정확합니다
    foreach (var t in Touch.activeTouches)
        if (EventSystem.current.IsPointerOverGameObject(t.touchId))
            return true;
    return false;
#endif
}

void HandleTap(Vector2 pos)
{
    if (PointerOnUI()) return;      // ★ UI 위면 게임 입력 무시
    FireAt(pos);
}

만들고 쓰기

1. Hierarchy 에서 완성된 오브젝트를
2. Project 창의 Prefabs 폴더로 드래그
3. 파란색으로 바뀌면 프리팹 완성
4. 원본을 고치면 → 배치된 것 전부 반영
5. 개별 인스턴스만 다르게 하려면 → Override

public class Spawner : MonoBehaviour
{
    [SerializeField] private GameObject enemyPrefab;
    [SerializeField] private Transform[] points;

    void Spawn()
    {
        var p = points[Random.Range(0, points.Length)];
        var go = Instantiate(enemyPrefab, p.position, Quaternion.identity);

        // 만든 직후 값 넣기
        go.GetComponent<Enemy>().Init(level: _wave);
    }
}

Instantiate 는 비쌉니다

Instantiate(bullet);   // 매번 힙 할당
Destroy(go);           // GC 대상 누적
// 초당 20발 → 프레임 튐

var b = _pool.Get();
b.SetActive(true);
// 다 쓰면
b.SetActive(false);
_pool.Release(b);

// Unity 내장 풀 (2021+)
using UnityEngine.Pool;

_pool = new ObjectPool<Bullet>(
    createFunc: () => Instantiate(prefab),
    actionOnGet: b => b.gameObject.SetActive(true),
    actionOnRelease: b => b.gameObject.SetActive(false),
    actionOnDestroy: b => Destroy(b.gameObject),
    defaultCapacity: 50, maxSize: 200);

프리팹 변형(Variant) — 원본 + 차이점만

Enemy.prefab            원본 — 이동·체력·드랍 공통
 ├ EnemyFast.variant    속도만 2배로 오버라이드
 ├ EnemyTank.variant    체력만 5배로 오버라이드
 └ EnemyBoss.variant    모델·크기·AI 추가

원본 Enemy 의 충돌 버그를 고치면
→ 변형 3종에 전부 반영 (오버라이드한 값만 유지)

만들기: Project 창에서 프리팹을 우클릭 → Create → Prefab Variant. 클래스 상속의 프리팹 버전이라고 생각하면 됩니다.

파란 글씨의 의미 — 오버라이드 관리

두 부품의 역할

void OnCollisionEnter(Collision c)      // 부딪힘 (둘 다 Collider, 하나는 Rigidbody)
{
    if (c.gameObject.CompareTag("Ground")) _grounded = true;
    var point = c.contacts[0].point;      // 맞은 지점
}

void OnTriggerEnter(Collider other)     // 통과 (isTrigger 체크)
{
    if (other.TryGetComponent<Item>(out var item)) Pickup(item);
}

움직이는 방법 — 이걸 틀립니다

// 빠른 총알이 벽을 통과할 때
rb.collisionDetectionMode = CollisionDetectionMode.ContinuousDynamic;

// 레이어로 충돌 규칙 정리 (Project Settings → Physics)
// 예: Player 는 PlayerBullet 과 충돌하지 않음 → 자기 총알에 안 맞음

// 레이캐스트로 미리 검사
if (Physics.Raycast(pos, dir, out var hit, dist, groundMask)) { }

2D 물리는 별도 세계입니다

// 2D 는 전부 2D 접미사 버전을 씁니다 — 서로 섞이지 않습니다
Rigidbody2D rb;
BoxCollider2D box;

void OnCollisionEnter2D(Collision2D c) { }   // 2D 이벤트
void OnTriggerEnter2D(Collider2D other) { }

// 플랫포머 점프 + 바닥 체크
[SerializeField] private LayerMask groundMask;

bool Grounded() =>
    Physics2D.OverlapCircle(feet.position, 0.15f, groundMask);

void Jump()
{
    if (!Grounded()) return;
    rb.linearVelocity = new Vector2(rb.linearVelocity.x, 0); // 낙하 중 점프 보정
    rb.AddForce(Vector2.up * jumpPower, ForceMode2D.Impulse);
}

물리 재질 · 조작감 다듬기

// "손맛 나는 점프" 공식 — 떨어질 때 중력을 더 세게
void FixedUpdate()
{
    if (rb.linearVelocity.y < 0)
        rb.linearVelocity += Vector2.up * Physics2D.gravity.y
                             * (fallMultiplier - 1) * Time.fixedDeltaTime;
}

Animator

구성 요소
  Animation Clip   실제 동작 (Idle · Run · Jump · Attack)
  Animator Controller  상태와 전환 규칙 (.controller 파일)
  Parameter        전환 조건 (float Speed · bool Grounded · trigger Attack)
  Layer            상반신/하반신 분리 등

private Animator _anim;
// ★ 문자열 대신 해시로 (매 프레임 문자열 비교를 피한다)
private static readonly int Speed    = Animator.StringToHash("Speed");
private static readonly int Grounded = Animator.StringToHash("Grounded");
private static readonly int AttackT  = Animator.StringToHash("Attack");

void Update()
{
    _anim.SetFloat(Speed, _rb.linearVelocity.magnitude);
    _anim.SetBool(Grounded, _grounded);
    if (Input.GetMouseButtonDown(0)) _anim.SetTrigger(AttackT);
}

// 애니메이션 중간에 이벤트 호출 (Animation Event 로 등록)
public void OnHitFrame() => DealDamage();

오디오

[SerializeField] private AudioClip shootClip;
private AudioSource _src;

void Awake() => _src = GetComponent<AudioSource>();

// 겹쳐 재생 (총소리처럼 빠르게 반복)
_src.PlayOneShot(shootClip, volumeScale: 0.7f);

// 한 지점에서 잠깐 나는 소리 — 오브젝트 없이
AudioSource.PlayClipAtPoint(explodeClip, pos);

// 음량 조절은 AudioMixer 로 (설정 화면과 연결)
mixer.SetFloat("BgmVolume", Mathf.Log10(Mathf.Max(v, 0.0001f)) * 20);   // dB 변환 (0 이면 -∞ 라 하한 -80dB)

코드 없는 연출 — Timeline · Cinemachine

// Cinemachine — 카메라 추적은 코드가 아니라 세팅입니다
// 1. Package Manager → Cinemachine 설치
// 2. Hierarchy 우클릭 → Cinemachine → Cinemachine Camera (2.x 는 Virtual Camera)
// 3. Follow 슬롯에 Player 드래그 — 끝

// 피격 시 화면 흔들기
using Unity.Cinemachine;
[SerializeField] private CinemachineImpulseSource impulse;
void OnHit() => impulse.GenerateImpulse();

코드 트윈 — "0.3초 만에 스르륵"

// 짧은 연출은 코루틴 트윈으로 충분합니다
IEnumerator PunchScale(Transform t, float dur = 0.25f)
{
    Vector3 baseS = t.localScale;
    for (float e = 0; e < dur; e += Time.deltaTime)
    {
        float k = e / dur;
        // 튀어 올랐다가 돌아오는 곡선
        float s = 1f + Mathf.Sin(k * Mathf.PI) * 0.25f;
        t.localScale = baseS * s;
        yield return null;
    }
    t.localScale = baseS;
}
// 버튼 클릭·아이템 획득·데미지 숫자에 이거 하나면 살아납니다

Canvas 설정

• Render Mode — 대부분 Screen Space - Overlay
• Canvas Scaler — Scale With Screen Size 로 두고 기준 해상도(예: 1920×1080) 지정 ★
• Match — 가로/세로 중 무엇에 맞출지 (모바일 세로 게임은 Width 쪽)
• Anchor — 화면 모서리에 붙이면 해상도가 바뀌어도 자리가 유지됩니다

using TMPro;

[SerializeField] private TMP_Text hpText;
[SerializeField] private Slider hpBar;
[SerializeField] private Button startBtn;

void Awake()
{
    startBtn.onClick.AddListener(StartGame);      // 코드로 연결
}
void OnDestroy() => startBtn.onClick.RemoveListener(StartGame);

void SetHp(int cur, int max)
{
    hpBar.value = (float)cur / max;
    hpText.SetText("{0}/{1}", cur, max);          // 할당 없는 API
}

느려지는 이유와 대책

• 캔버스를 나누세요 — 자주 바뀌는 것(HUD)과 안 바뀌는 것(메뉴)을 분리
• Raycast Target 끄기 — 클릭이 필요 없는 이미지·텍스트는 전부 해제
• 텍스트는 TextMeshPro — 기본 Text 는 화질·성능 모두 불리합니다
• 비활성화보다 캔버스 그룹 — alpha 0 + blocksRaycasts false 가 더 쌉니다
• 레이아웃 그룹 남용 금지 — 중첩되면 계산 비용이 급증합니다

한글이 네모(□)로 나올 때 — TMP 폰트 만들기

TextMeshPro 기본 폰트에는 한글이 없습니다.

1. 한글 폰트 준비 (예: Pretendard · 무료 상업 허용)
   → ttf/otf 를 Assets 에 넣기
2. Window → TextMeshPro → Font Asset Creator
3. Source Font: 넣은 폰트
   Sampling Point Size: Auto
   Atlas Resolution : 4096 × 4096
   Character Set    : Custom Characters 또는
                      Unicode Range (Hex)
   한글 완성형 범위 : AC00-D7A3, 3130-318F
4. Generate → Save → TMP_Text 의 Font Asset 교체

자주 만드는 UI 패턴

// 부드럽게 차는 체력바
IEnumerator FillTo(float target)
{
    float from = hpBar.value;
    for (float e = 0; e < 0.25f; e += Time.deltaTime)
    {
        hpBar.value = Mathf.Lerp(from, target, e / 0.25f);
        yield return null;
    }
    hpBar.value = target;
}

// 데미지 숫자 — 월드 위치를 따라가는 UI
void LateUpdate()
{
    var screen = cam.WorldToScreenPoint(target.position + Vector3.up * 2f);
    rect.position = screen;
}

// 페이드 인/아웃 — CanvasGroup 하나로
IEnumerator Fade(CanvasGroup g, float to, float dur)
{
    float from = g.alpha;
    for (float e = 0; e < dur; e += Time.unscaledDeltaTime)  // 일시정지 중에도
    { g.alpha = Mathf.Lerp(from, to, e / dur); yield return null; }
    g.alpha = to;
    g.blocksRaycasts = to > 0.5f;
}

씬 로딩

using UnityEngine.SceneManagement;

SceneManager.LoadScene("Game");                    // 즉시 (멈칫함)

// 비동기 + 로딩바 (권장)
IEnumerator LoadAsync(string name)
{
    var op = SceneManager.LoadSceneAsync(name);
    op.allowSceneActivation = false;               // 다 될 때까지 대기

    while (op.progress < 0.9f)
    {
        bar.value = op.progress / 0.9f;
        yield return null;
    }
    bar.value = 1f;
    yield return new WaitForSeconds(0.3f);         // 로딩바를 잠깐 보여 주기
    op.allowSceneActivation = true;
}

// 겹쳐 올리기 (UI 씬 · 스테이지 추가)
SceneManager.LoadScene("Pause", LoadSceneMode.Additive);

씬을 넘어 살아남기

public class GameManager : MonoBehaviour
{
    public static GameManager Instance { get; private set; }

    void Awake()
    {
        if (Instance != null && Instance != this) { Destroy(gameObject); return; }
        Instance = this;
        DontDestroyOnLoad(gameObject);      // 씬이 바뀌어도 유지
    }
}

게임 상태 기계 — 흐름을 enum 하나로

public enum GameState { Title, Playing, Paused, GameOver }

public class GameFlow : MonoBehaviour
{
    public GameState State { get; private set; } = GameState.Title;
    public event System.Action<GameState> OnStateChanged;

    public void SetState(GameState next)
    {
        if (State == next) return;
        State = next;
        Time.timeScale = next == GameState.Paused ? 0f : 1f;
        OnStateChanged?.Invoke(next);        // UI·사운드가 알아서 반응
    }
}

// 구독하는 쪽 — UI 는 상태를 "물어보지" 않고 "통보받습니다"
void OnEnable()  => flow.OnStateChanged += HandleState;
void OnDisable() => flow.OnStateChanged -= HandleState;

void HandleState(GameState s)
{
    pausePanel.SetActive(s == GameState.Paused);
    hud.SetActive(s == GameState.Playing);
}

왜 이렇게 하나

• if (isPaused && !isGameOver && ...) 지옥을 예방 — 상태가 하나의 enum 이면 조합 폭발이 없습니다
• 전환 규칙이 한 곳에 — 일시정지 중 사망 처리 같은 엣지 케이스를 SetState 한 군데서 막습니다
• 이벤트 구독 패턴 — UI·사운드·입력이 각자 반응하므로 GameFlow 는 그들의 존재를 몰라도 됩니다

ScriptableObject — 데이터를 에셋으로

[CreateAssetMenu(fileName = "Item", menuName = "Game/Item")]
public class ItemData : ScriptableObject
{
    public string displayName;
    public Sprite icon;
    public int    price;
    public int    attack;
    [TextArea] public string description;
}

// 쓰는 쪽
public class Shop : MonoBehaviour
{
    [SerializeField] private ItemData[] stock;   // 인스펙터에서 드래그
}

• 메모리에 한 벌만 존재합니다 — 프리팹마다 복사되지 않습니다
• 기획자가 직접 값을 수정할 수 있습니다(코드 수정·재빌드 불필요)
• 밸런스 표를 엑셀 → SO 자동 생성하는 파이프라인이 흔합니다

세이브

[Serializable]
public class SaveData
{
    public int level;
    public int gold;
    public List<string> unlocked = new();
}

static string Path => System.IO.Path.Combine(
    Application.persistentDataPath, "save.json");   // ★ 반드시 이 경로

public static void Save(SaveData d)
{
    var json = JsonUtility.ToJson(d, prettyPrint: true);
    var tmp  = Path + ".tmp";
    File.WriteAllText(tmp, json);
    if (File.Exists(Path)) File.Replace(tmp, Path, null);   // 쓰다 꺼져도 원본 보존
    else                   File.Move(tmp, Path);            // (Copy 는 덮어쓰는 도중 꺼지면 깨집니다)
}

public static SaveData Load() =>
    File.Exists(Path) ? JsonUtility.FromJson<SaveData>(File.ReadAllText(Path))
                      : new SaveData();

JsonUtility 가 못 하는 것 — 미리 알아 두세요

세이브 버전 올리기 — 업데이트에도 안 깨지게

[Serializable]
public class SaveData
{
    public int version = 2;      // ★ 처음부터 넣어 두세요
                                 //   (이 필드가 없던 옛 세이브는 초기값 2 로 읽혀
                                 //    아래 마이그레이션을 건너뜁니다)
    public int level;
    public int gold;
    public List<string> unlocked = new();
}

public static SaveData Load()
{
    if (!File.Exists(Path)) return new SaveData();
    var d = JsonUtility.FromJson<SaveData>(File.ReadAllText(Path));

    // 구버전 세이브를 단계적으로 끌어올린다
    if (d.version < 2)
    {
        d.gold += 100;           // v2 보상 지급 예시
        d.version = 2;
    }
    return d;
}

증상별 원인

습관으로 막기

• 파일명과 클래스명을 항상 같게 — Unity 규칙입니다
• 인스펙터 참조는 실행 전에 확인 — 비었으면 Awake 에서 경고 로그
• 버전 관리(Git)에 Library/ 는 제외 — .gitignore 는 Unity 템플릿 사용
• 씬은 자주 저장(Ctrl+S) — 크래시가 나면 그대로 날아갑니다
• 에디터 로그를 켜 두세요 — 경고를 무시하면 빌드에서 터집니다

void Awake()
{
    if (muzzle == null)
        Debug.LogError($"{name}: muzzle 이 비었습니다", this);  // ← 클릭하면 그 오브젝트로 이동
}

씬에 그려서 확인하기

void Update()
{
    // Scene 창에 선이 그려집니다 (Game 창은 Gizmos 버튼 ON)
    Debug.DrawRay(transform.position, transform.forward * 5f, Color.red);
    Debug.DrawLine(a, b, Color.yellow, duration: 2f);
}

// 선택했을 때만 공격 범위 표시
void OnDrawGizmosSelected()
{
    Gizmos.color = new Color(1, 0, 0, 0.3f);
    Gizmos.DrawWireSphere(transform.position, attackRange);
}

일시정지 · 프레임 단위 관찰

• Pause + Step(▶ 옆 버튼) — 한 프레임씩 진행하며 Inspector 값 변화를 관찰
• Error Pause — Console 탭에서 켜면 에러가 난 그 프레임에서 자동 정지
• Debug.Break() — 코드에서 조건 걸어 정지: if (hp < 0) Debug.Break();
• Console 의 로그를 클릭하면 해당 코드 줄로, Debug.Log("msg", this) 의 로그를 클릭하면 그 오브젝트가 하이라이트됩니다

// 로그는 세 단계 + 컨텍스트를 습관으로
Debug.Log($"[Spawner] wave {_wave} 시작", this);
Debug.LogWarning("풀 고갈 — maxSize 확인", this);
Debug.LogError("세이브 파일 손상", this);

// 빌드에서 로그 비용 제거
[System.Diagnostics.Conditional("UNITY_EDITOR")]
static void DevLog(string msg) => Debug.Log(msg);

코루틴 — 시간 흐름을 함수 하나로

using System.Collections;
using UnityEngine;

public class DashSkill : MonoBehaviour
{
    [SerializeField] private float cooldown = 2f;
    private bool _ready = true;

    public void TryDash()
    {
        if (!_ready) return;
        StartCoroutine(DashRoutine());
    }

    IEnumerator DashRoutine()          // ★ 반환형이 IEnumerator
    {
        _ready = false;
        // 0.2초 동안 프레임마다 이동 — 시간 흐름이 for 문처럼 읽힙니다
        for (float e = 0; e < 0.2f; e += Time.deltaTime)
        {
            transform.Translate(Vector3.forward * 30f * Time.deltaTime);
            yield return null;         // 다음 프레임까지 양보
        }
        yield return new WaitForSeconds(cooldown);
        _ready = true;
    }
}

yield return 은 "여기서 멈췄다가, 조건이 되면 이어서" 입니다. 상태 변수·타이머를 Update 에 흩뿌리지 않고 절차를 위에서 아래로 쓸 수 있다는 것이 코루틴의 가치입니다.

WaitForSeconds 는 캐싱하세요

// 나쁨 — 루프마다 new → GC 쓰레기가 쌓여 가끔 프레임이 튑니다
IEnumerator SpawnLoopBad()
{
    while (true) { Spawn(); yield return new WaitForSeconds(1f); }
}

// 좋음 — 한 번 만들어 재사용
IEnumerator SpawnLoop()
{
    var wait = new WaitForSeconds(1f);       // ★ 밖에서 한 번만
    while (true) { Spawn(); yield return wait; }
}

// 일시정지(Time.timeScale = 0) 중에도 흘러야 한다면
yield return new WaitForSecondsRealtime(0.5f);

중단 관리 — 코루틴이 소리 없이 죽는 곳

// 핸들을 잡아 두고, 꺼질 때 반드시 정리
Coroutine _flow;

void OnEnable()  => _flow = StartCoroutine(Flow());
void OnDisable()
{
    if (_flow != null) StopCoroutine(_flow);
    _flow = null;
}

// 전부 멈추기 — 이 컴포넌트가 시작한 것만
StopAllCoroutines();

Invoke — 간단한 지연 한 방이면 충분할 때

Invoke(nameof(Explode), 3f);            // 3초 뒤 Explode() 한 번
InvokeRepeating(nameof(Spawn), 1f, 2f); // 1초 뒤부터 2초마다 반복

CancelInvoke(nameof(Spawn));            // 예약 취소
if (IsInvoking(nameof(Explode))) { }    // 예약돼 있나?

// ★ nameof 를 쓰면 이름 변경 시 컴파일 에러로 잡힙니다
//    "Explode" 처럼 문자열로 쓰면 조용히 깨집니다

Awaitable (Unity 6 내장)

// destroyCancellationToken — 오브젝트가 파괴되면 자동 취소 ★
async Awaitable Die()                   // async void 대신 Awaitable
{
    try { await Awaitable.WaitForSecondsAsync(3f, destroyCancellationToken); }
    catch (OperationCanceledException) { return; }   // 파괴되면 조용히 끝
    Respawn();
}

// 무거운 계산은 스레드 풀로 보냈다가 메인으로 복귀
async Awaitable BuildMapAsync()
{
    await Awaitable.BackgroundThreadAsync();
    var data = GenerateHeavyMap();      // 여기서 Unity API 호출 금지
    await Awaitable.MainThreadAsync();
    ApplyToTilemap(data);               // Unity API 는 메인 스레드에서만
}

UniTask — 실무 표준 비동기 라이브러리

// 설치: Window → Package Manager → 좌상단 + →
//       Add package from git URL →
//       https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask
using Cysharp.Threading.Tasks;

async UniTask<int> RollDiceAsync()
{
    await UniTask.Delay(1000,
        cancellationToken: this.GetCancellationTokenOnDestroy());
    return Random.Range(1, 7);          // ★ 코루틴은 못 하는 "반환값"
}

// 여러 개를 동시에 기다리기
var (a, b) = await UniTask.WhenAll(LoadPlayerAsync(), LoadStageAsync());

• 무할당(zero allocation) — Task 보다 가볍고 GC 부담이 없습니다
• 반환값·예외·취소 — 코루틴이 못 하는 세 가지를 전부 합니다
• WebGL 포함 전 플랫폼 동작 · 코루틴의 모든 yield 대응물 제공

Camera 컴포넌트 기본

Camera cam = Camera.main;          // Awake 에서 캐시 (u04 참고)

// 3D — 원근(Perspective): 멀수록 작게
cam.fieldOfView = 60f;             // 시야각 — 좁히면 망원, 넓히면 광각

// 2D — 직교(Orthographic): 거리와 무관하게 같은 크기
cam.orthographic = true;
cam.orthographicSize = 5f;         // 화면 세로 "절반"이 5유닛

직접 짤 때의 함정 — LateUpdate

public class FollowCam : MonoBehaviour
{
    [SerializeField] private Transform target;
    [SerializeField] private Vector3 offset = new(0, 5, -8);
    [SerializeField] private float smooth = 0.2f;
    private Vector3 _vel;

    void LateUpdate()   // ★ Update 에서 하면 안 됩니다
    {
        transform.position = Vector3.SmoothDamp(
            transform.position, target.position + offset,
            ref _vel, smooth);
    }
}

도입 5분 코스

1. Window → Package Manager → Unity Registry → Cinemachine 설치
2. Hierarchy 우클릭 → Cinemachine → Cinemachine Camera
   (Unity 6 = Cinemachine 3.x. 2022 LTS 의 2.x 에서는
    "Virtual Camera" 라는 이름이고 네임스페이스가 Cinemachine 입니다)
3. Main Camera 에 CinemachineBrain 이 자동으로 붙음
4. Cinemachine Camera 의 Follow 슬롯에 Player 드래그 — 끝
5. Position Control → Follow 방식과 Damping 으로 감을 조절

• 실제 카메라는 Main Camera 하나 — Cinemachine Camera 는 "여기서 이렇게 찍어라"는 지시서입니다
• 지시서를 여러 개 두고 Priority 가 높은 쪽을 따라갑니다 — 보스 등장 시 보스 카메라의 Priority 를 올리면 부드럽게 블렌드되며 전환
• Confiner 익스텐션 — 카메라가 맵 밖을 못 보게 제한. 2D 는 CinemachineConfiner2D + 경계용 PolygonCollider2D

화면 흔들림(Impulse) · 2D 와 3D

using Unity.Cinemachine;   // 2.x 는 using Cinemachine;

// 흔드는 쪽 — 피격·폭발 지점에 ImpulseSource 붙이기
[SerializeField] private CinemachineImpulseSource impulse;
void OnHit() => impulse.GenerateImpulse(0.5f);   // 세기

// 받는 쪽 — Cinemachine Camera 에
// Add Extension → CinemachineImpulseListener 추가하면 끝

Sprite 와 Pixels Per Unit

이미지를 Assets 에 넣으면 → Texture Type: Sprite (2D and UI)

Pixels Per Unit (PPU) = "몇 픽셀이 1유닛인가"
  PPU 100, 이미지 200px → 씬에서 2유닛 크기
  16×16 픽셀 아트라면  → PPU 16 으로 두면 타일 1칸 = 1유닛

한 장에 여러 캐릭터가 있는 스프라이트 시트라면
  Sprite Mode: Multiple → Sprite Editor 에서 Slice

그리기 순서 — Sorting Layer

var sr = GetComponent<SpriteRenderer>();

// 큰 분류는 레이어로 (Project Settings → Tags and Layers 에서 추가)
// Background → Ground → Characters → Effects → 순서대로 위에 그려짐
sr.sortingLayerName = "Characters";

// 같은 레이어 안 순서는 숫자로 — 클수록 앞
sr.sortingOrder = 10;

sr.flipX = dir.x < 0;        // 좌우 반전은 회전 대신 이걸로 (u04)

기본 흐름 + 충돌까지

1. Hierarchy 우클릭 → 2D Object → Tilemap → Rectangular
   (Grid 오브젝트 밑에 Tilemap 이 생김)
2. Window → 2D → Tile Palette → Create New Palette
3. 잘라 둔 타일 스프라이트를 팔레트 창에 드래그
4. 브러시(B)로 씬에 그리기 · 지우개는 Shift+드래그

충돌 붙이기 — 타일 하나하나가 아니라 한 방에:
5. Tilemap 오브젝트에 Tilemap Collider 2D 추가
6. Composite Collider 2D 추가 (콜라이더를 하나로 합침)
   → 자동으로 붙는 Rigidbody2D 는 Body Type: Static
7. Tilemap Collider 2D 의 Composite Operation: Merge

Rule Tile — 지형이 스스로 이어 붙게

Window → Package Manager → 2D Tilemap Extras 설치

Project 우클릭 → Create → 2D → Tiles → Rule Tile
→ 규칙마다 "주변에 타일이 있으면/없으면 이 스프라이트" 지정
→ 팔레트에 Rule Tile 을 넣고 그리면
   모서리·가장자리·안쪽 타일을 알아서 골라 줍니다

모서리 타일을 손으로 골라 깔던 작업이 브러시 한 번으로 끝납니다. 지형 종류마다 Rule Tile 하나씩 만들어 두는 것이 2D 맵 작업의 표준입니다.

2D 물리 — 3D 와 다른 점

픽셀 아트가 흐릿할 때 — 임포트 3종 세트

스프라이트를 선택 → Inspector 에서

Filter Mode : Point (no filter)   ← 뭉개짐 제거 ★
Compression : None                ← 색 번짐 제거
Pixels Per Unit : 타일 크기와 동일 (16픽셀 타일이면 16)

여러 장을 한 번에: 전부 선택 후 같은 설정 → Apply
아예 Preset 으로 저장해 두면 새 에셋에 자동 적용됩니다

NavMesh 베이크 — "걸을 수 있는 곳" 지도 만들기

1. Window → Package Manager → AI Navigation 설치
   (Unity 6 에는 기본 포함)
2. 바닥·벽이 담긴 오브젝트(또는 빈 부모)에
   Add Component → Navigation → NavMeshSurface
3. NavMeshSurface 의 [Bake] 버튼
   → 씬에 파란 영역 = 에이전트가 걸을 수 있는 곳
4. 움직이는 장애물(문·상자)에는 NavMeshObstacle
   → Carve 체크 시 지도에 실시간으로 구멍을 팝니다

NavMeshAgent — 목적지만 주면 알아서

using UnityEngine.AI;

private NavMeshAgent _agent;
void Awake() => _agent = GetComponent<NavMeshAgent>();

void Chase()
{
    _agent.speed = 3.5f;
    _agent.stoppingDistance = 1.5f;   // 공격 사거리 앞에서 멈춤
    _agent.SetDestination(player.position);
}

// "도착했나" 판정 — pathPending 체크를 빼먹으면 오판합니다
bool Arrived =>
    !_agent.pathPending &&
    _agent.remainingDistance <= _agent.stoppingDistance;

복붙해서 시작하는 적 AI

using UnityEngine;
using UnityEngine.AI;

public class EnemyAI : MonoBehaviour
{
    enum State { Patrol, Chase, Attack }        // u10 의 게임 상태와 같은 패턴

    [SerializeField] private Transform[] waypoints;
    [SerializeField] private Transform player;
    [SerializeField] private float sightRange  = 8f;
    [SerializeField] private float attackRange = 1.8f;

    private NavMeshAgent _agent;
    private State _state = State.Patrol;
    private int _wp;

    void Awake() => _agent = GetComponent<NavMeshAgent>();

    void Update()
    {
        float dist = Vector3.Distance(transform.position, player.position);

        // 1) 전환 규칙 — 한 곳에 모아 둡니다
        switch (_state)
        {
            case State.Patrol:
                if (CanSee(dist)) _state = State.Chase;
                break;
            case State.Chase:
                if (dist <= attackRange)          _state = State.Attack;
                else if (dist > sightRange * 1.5f) _state = State.Patrol;  // 놓침
                break;
            case State.Attack:
                if (dist > attackRange) _state = State.Chase;
                break;
        }

        // 2) 상태별 행동
        switch (_state)
        {
            case State.Patrol:
                _agent.isStopped = false;
                if (!_agent.pathPending && _agent.remainingDistance < 0.3f)
                {
                    _wp = (_wp + 1) % waypoints.Length;   // 다음 지점 순환
                    _agent.SetDestination(waypoints[_wp].position);
                }
                break;
            case State.Chase:
                _agent.isStopped = false;
                _agent.SetDestination(player.position);
                break;
            case State.Attack:
                _agent.isStopped = true;                  // 멈춰서
                transform.LookAt(player);                 // 바라보고
                TryAttack();                              // 쿨다운은 내부에서
                break;
        }
    }
}

시야 판정 — "봤다"를 코드로

bool CanSee(float dist)
{
    if (dist > sightRange) return false;

    var dir = (player.position - transform.position).normalized;

    // 시야각 120도 — 등 뒤는 못 봅니다 (u04 의 Dot 판정)
    if (Vector3.Dot(transform.forward, dir)
        < Mathf.Cos(60f * Mathf.Deg2Rad)) return false;

    // 벽에 가렸나 — 눈높이에서 레이 하나
    var eye = transform.position + Vector3.up * 1.6f;
    if (Physics.Raycast(eye, dir, out var hit, sightRange)
        && !hit.transform.CompareTag("Player"))
        return false;                       // 먼저 맞은 것이 벽

    return true;
}

Particle System — 이 모듈만 먼저

Hierarchy 우클릭 → Effects → Particle System

히트 이펙트 레시피 (5분)
  Main     : Duration 0.5 · Looping 끔 · Start Speed 3~6
  Emission : Rate 0 · Bursts + → Count 20
  Shape    : Sphere · Radius 0.1
  Color over Lifetime : 알파 1 → 0
  Renderer : Material 을 파티클용으로 (URP/Particles/Unlit)

나머지 수십 개 모듈은 필요할 때 하나씩 켜 보면 됩니다. 전부 이해하고 시작하려는 순간 여기서 멈추게 됩니다.

재생과 풀링 — 이펙트도 부품입니다

[SerializeField] private ParticleSystem hitFx;

public void PlayHit(Vector3 pos)
{
    hitFx.transform.position = pos;
    hitFx.Play();                    // 재생 중이면 겹쳐 방출
}

// 풀링과 연결 (u06 의 ObjectPool 그대로)
// 프리팹의 Main → Stop Action: Callback 으로 설정하면
// 파티클이 다 끝났을 때 이 콜백이 옵니다
public class PooledEffect : MonoBehaviour
{
    public System.Action<PooledEffect> OnFinished;

    void OnParticleSystemStopped()   // ★ 반납 타이밍을 엔진이 알려 줌
        => OnFinished?.Invoke(this);
}

Shader Graph — 노드로 셰이더 만들기

전제: URP 프로젝트 (u01 에서 권장한 그 템플릿)

Project 우클릭 → Create → Shader Graph → URP
→ Lit Shader Graph
→ 더블클릭으로 그래프 창 열기
→ 노드를 연결하면 그대로 셰이더 코드로 컴파일됩니다

입문 단골 예제
  피격 플래시   Color 프로퍼티를 Base Color 에 Lerp
  외곽선 발광   Fresnel Effect 노드 → Emission
  디졸브       Simple Noise → Alpha Clip Threshold

// 그래프에서 노출한 프로퍼티를 코드로 제어
private static readonly int Flash = Shader.PropertyToID("_FlashAmount");

void OnHit() => _renderer.material.SetFloat(Flash, 1f);

Post Processing — URP Volume

1. Hierarchy 우클릭 → Volume → Global Volume
2. Profile 옆 [New] → Add Override → Post-processing
3. Bloom    : Threshold 1.1 · Intensity 0.6
              밝은 부분만 번지게 — 네온·마법 이펙트의 그 빛
4. Vignette : Intensity 0.3
              가장자리를 어둡게 — 화면 집중도가 올라감
5. 안 보이면 → Main Camera 의 Rendering →
              Post Processing 체크 확인

Bloom 으로 빛나게 하려면 재질 쪽도 필요합니다 — 머티리얼의 Emission 을 켜고 HDR 색상 Intensity 를 1 이상으로. Threshold 를 넘는 밝기만 번집니다.

폴더 규칙

Assets/
  _Project/              ← 우리 코드·에셋 (밑줄로 맨 위 고정)
    Scripts/
      Core/              공용 유틸 · 이벤트 버스
      Gameplay/          플레이어 · 적 · 전투
      UI/
      Data/              ScriptableObject 정의
      Editor/            에디터 확장 (빌드에 포함 안 됨)
    Prefabs/  Scenes/  Art/  Audio/  Settings/
  Plugins/               외부 SDK
  StreamingAssets/       빌드 후에도 파일로 남는 것

Assembly Definition — 컴파일 시간을 줄인다

// Scripts/Gameplay/Gameplay.asmdef
{
  "name": "Game.Gameplay",
  "references": ["Game.Core", "Unity.InputSystem"],
  "autoReferenced": false
}

• 고친 어셈블리만 다시 컴파일됩니다 — 저장 후 대기 시간이 몇 배 줄어듭니다
• 의존 방향을 강제할 수 있습니다 (Core 가 UI 를 참조하면 컴파일 에러)
• 테스트 어셈블리를 따로 두면 빌드에서 자동 제외됩니다

직접 만들기 (원리)

public class BulletPool : MonoBehaviour
{
    [SerializeField] private Bullet prefab;
    [SerializeField] private int prewarm = 50;

    private readonly Stack<Bullet> _idle = new();

    void Awake()
    {
        for (int i = 0; i < prewarm; i++)     // ★ 로딩 때 미리 만든다
        {
            var b = Instantiate(prefab, transform);
            b.gameObject.SetActive(false);
            _idle.Push(b);
        }
    }

    public Bullet Get(Vector3 pos, Quaternion rot)
    {
        var b = _idle.Count > 0 ? _idle.Pop() : Instantiate(prefab, transform);
        b.transform.SetPositionAndRotation(pos, rot);
        b.gameObject.SetActive(true);
        return b;
    }

    public void Release(Bullet b)
    {
        b.gameObject.SetActive(false);
        b.ResetState();                        // ★ 상태 초기화를 잊지 마세요
        _idle.Push(b);
    }
}

놓치기 쉬운 것

• 상태 초기화 — 속도·남은 시간·트레일이 남아 있으면 "이상하게 동작하는 총알"이 됩니다
• 파티클은 Stop(true, ClearBehaviour.Clear) 로 잔상 제거
• 코루틴은 비활성화되면 멈춥니다 — 재활성화 시 다시 시작해야 합니다
• 이벤트 구독은 OnEnable/OnDisable 짝으로
• 최대 개수 상한을 두세요 — 무한히 늘면 그냥 메모리 누수입니다

풀 말고도 GC 를 만드는 것들

// RaycastAll → NonAlloc 패턴
static readonly RaycastHit[] s_hits = new RaycastHit[16];

int n = Physics.RaycastNonAlloc(ray, s_hits, dist, mask);
for (int i = 0; i < n; i++) Process(s_hits[i]);

풀 매니저 — 프리팹별 풀을 하나로

public class PoolHub : MonoBehaviour
{
    static readonly Dictionary<GameObject, ObjectPool<GameObject>> s_pools = new();

    public static GameObject Spawn(GameObject prefab, Vector3 pos, Quaternion rot)
    {
        if (!s_pools.TryGetValue(prefab, out var pool))
        {
            pool = new ObjectPool<GameObject>(
                () => { var g = Instantiate(prefab); g.AddComponent<PoolTag>().Origin = prefab; return g; },
                g => g.SetActive(true),
                g => g.SetActive(false),
                Destroy, defaultCapacity: 32, maxSize: 256);
            s_pools[prefab] = pool;
        }
        var go = pool.Get();
        go.transform.SetPositionAndRotation(pos, rot);
        return go;
    }

    public static void Despawn(GameObject go) =>
        s_pools[go.GetComponent<PoolTag>().Origin].Release(go);
}
// 사용처는 Instantiate/Destroy 를 Spawn/Despawn 으로 바꾸기만

Profiler 읽는 순서

• ① 실제 기기에 연결 — 에디터 수치는 참고용일 뿐입니다(Development Build 체크)
• ② CPU 그래프에서 튀는 구간을 클릭 → Timeline 으로 원인 함수 확인
• ③ GC Alloc 열을 정렬 — 0 B 가 아닌 것부터 없앱니다
• ④ Rendering — Batches · SetPass Calls · Tris 를 봅니다
• ⑤ Memory — 텍스처가 대부분입니다. Memory Profiler 패키지로 상세 분석

using Unity.Profiling;

// 내 코드 구간에 이름을 붙여 Profiler 에 표시
static readonly ProfilerMarker s_ai = new("Game.AI.Think");

void Think()
{
    using (s_ai.Auto())
    {
        // ... 무거운 AI 계산
    }
}

숫자 기준

배칭 — 여러 개를 한 번에

• Static Batching — 안 움직이는 물체에 Static 체크. 메모리를 쓰지만 효과가 큽니다
• SRP Batcher — URP 기본. 같은 셰이더면 재질이 달라도 묶입니다
• GPU Instancing — 같은 메시·재질을 수백 개 (풀·나무·적)
• 텍스처 아틀라스 — 여러 이미지를 한 장으로 합쳐 재질 수를 줄입니다

private static readonly int ColorId = Shader.PropertyToID("_BaseColor");
private MaterialPropertyBlock _mpb;

void Awake() => _mpb = new MaterialPropertyBlock();

void SetColor(Color c)
{
    _renderer.GetPropertyBlock(_mpb);
    _mpb.SetColor(ColorId, c);
    _renderer.SetPropertyBlock(_mpb);   // 재질 복제 없이 색만 변경
}

그 밖의 큰 것들

• 실시간 그림자를 줄이세요 — 모바일에서 가장 비쌉니다. 라이트맵 굽기로 대체
• 라이트는 굽고(Baked), 움직이는 것만 실시간
• Overdraw — 반투명(파티클·UI)이 겹치면 픽셀을 여러 번 그립니다
• LOD — 멀리 있는 모델은 저해상도로 교체
• 오클루전 컬링 — 벽 뒤 물체를 아예 안 그림
• 텍스처 압축 — Android ASTC, iOS ASTC, PC DXT

기본 사용

using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

private AsyncOperationHandle<GameObject> _handle;

async void LoadBoss()
{
    _handle = Addressables.LoadAssetAsync<GameObject>("Boss_Dragon");
    var prefab = await _handle.Task;
    Instantiate(prefab);
}

void OnDestroy()
{
    // ★ 반드시 해제 — 안 하면 메모리에 계속 남습니다
    if (_handle.IsValid()) Addressables.Release(_handle);
}

// 인스턴스까지 한 번에 (해제도 함께)
var go = await Addressables.InstantiateAsync("Boss_Dragon").Task;
Addressables.ReleaseInstance(go);

운영 관점

• 초기 설치 용량을 줄입니다 — 스토어 상한(구글 150MB 등)을 넘기지 않게
• 콘텐츠만 갱신 가능 — 앱 심사 없이 이벤트 에셋 교체(원격 카탈로그)
• 중복 제거 — 여러 번들이 같은 텍스처를 물면 메모리가 두 배가 됩니다
• 다운로드 진행률을 사용자에게 보여 주세요

// 다운로드 크기 확인 후 진행
var size = await Addressables.GetDownloadSizeAsync(label).Task;
if (size > 0)
{
    var dl = Addressables.DownloadDependenciesAsync(label);
    while (!dl.IsDone) { bar.value = dl.PercentComplete; await Task.Yield(); }
    Addressables.Release(dl);
}

그룹 설계 — 무엇을 어디에 담나

씬 전환과 메모리 수명

// 스테이지 진입 — 라벨 단위로 미리 받고, 나갈 때 통째로 해제
public class StageLoader
{
    readonly List<AsyncOperationHandle> _held = new();

    public async Task EnterAsync(string label)
    {
        var locs = await Addressables.LoadResourceLocationsAsync(label).Task;
        foreach (var loc in locs)
        {
            var h = Addressables.LoadAssetAsync<Object>(loc);
            _held.Add(h);
            await h.Task;
        }
    }

    public void Exit()
    {
        foreach (var h in _held) Addressables.Release(h);
        _held.Clear();
        // 씬 언로드 후 남은 것 정리
        Resources.UnloadUnusedAssets();
    }
}

Job + Burst 부터

using Unity.Burst;
using Unity.Collections;
using Unity.Jobs;
using Unity.Mathematics;

[BurstCompile]                                  // ★ 네이티브 수준으로 컴파일
public struct MoveJob : IJobParallelFor
{
    [ReadOnly] public NativeArray<float3> Dir;
    public NativeArray<float3> Pos;
    public float Dt;

    public void Execute(int i) => Pos[i] += Dir[i] * Dt;
}

// 실행
var job = new MoveJob { Pos = _pos, Dir = _dir, Dt = Time.deltaTime };
var handle = job.Schedule(_pos.Length, innerloopBatchCount: 64);
handle.Complete();                              // 결과가 필요한 시점에

언제 도입할 것인가

Transform 수천 개도 Job 으로 — TransformAccessArray

using UnityEngine.Jobs;

[BurstCompile]
struct SwarmJob : IJobParallelForTransform
{
    [ReadOnly] public NativeArray<float3> Vel;
    public float Dt;

    public void Execute(int i, TransformAccess t) =>
        t.position += (Vector3)(Vel[i] * Dt);
}

TransformAccessArray _tfs;    // 스폰 시 Add, 파괴 시 RemoveAtSwapBack

void Update()
{
    var job = new SwarmJob { Vel = _vel, Dt = Time.deltaTime };
    _handle = job.Schedule(_tfs);   // Transform 인데도 워커 스레드에서 돈다
}
void LateUpdate() => _handle.Complete();

"Job 은 Transform 을 못 쓴다"의 예외 통로입니다 — 군중 이동·총알 수천 발이 메인 스레드를 떠납니다.

Complete() 를 어디서 부를 것인가

var h = job.Schedule(n, 64);
h.Complete();   // 메인이 그냥 기다림
// = 멀티코어 효과 없음

// Update 에서 Schedule
_h = job.Schedule(n, 64);
// LateUpdate 에서 회수
_h.Complete();
// 그 사이 워커가 일한다

먼저 할 것

void Awake()
{
    Application.targetFrameRate = 60;      // ★ 안 정하면 기기 맘대로
    QualitySettings.vSyncCount = 0;
    Screen.sleepTimeout = SleepTimeout.NeverSleep;   // 필요할 때만
}

// 저사양 기기 자동 판별
if (SystemInfo.systemMemorySize < 3000)
{
    QualitySettings.SetQualityLevel(0);
    Application.targetFrameRate = 30;      // 30 고정이 60 널뛰기보다 낫습니다
}

• 해상도를 낮추세요 — Screen.SetResolution 으로 70~80% 만 써도 체감 차이가 적습니다
• Texture Quality·Shadow Distance를 품질 레벨로 묶어 관리
• 배터리·발열은 GPU 부하가 주범 — 해상도와 Overdraw 부터

빌드 설정

빌드 스크립트

// Assets/_Project/Scripts/Editor/BuildScript.cs
public static class BuildScript
{
    public static void BuildAndroid()
    {
        PlayerSettings.Android.useCustomKeystore = true;
        PlayerSettings.Android.keystorePass = Env("KEYSTORE_PASS");
        PlayerSettings.bundleVersion = Env("BUILD_VERSION");
        EditorUserBuildSettings.buildAppBundle = true;   // .aab 로 (끄면 APK 가 나옵니다)
        PlayerSettings.Android.bundleVersionCode = int.Parse(Env("BUILD_NUMBER"));

        var opts = new BuildPlayerOptions
        {
            scenes = EditorBuildSettings.scenes
                        .Where(s => s.enabled).Select(s => s.path).ToArray(),
            locationPathName = "build/game.aab",
            target = BuildTarget.Android,
            options = BuildOptions.None,
        };

        var report = BuildPipeline.BuildPlayer(opts);
        if (report.summary.result != BuildResult.Succeeded)
            EditorApplication.Exit(1);          // CI 에 실패를 알린다
    }
    static string Env(string k) => System.Environment.GetEnvironmentVariable(k) ?? "";
}

Unity -quit -batchmode -nographics \
  -projectPath . -executeMethod BuildScript.BuildAndroid \
  -logFile build.log

출시 체크리스트

• ☐ 버전·빌드 번호 자동 증가 (수동은 반드시 실수합니다)
• ☐ 키스토어 백업 — 잃으면 앱을 영원히 업데이트할 수 없습니다
• ☐ 개발용 로그·치트 코드 제거 (#if DEVELOPMENT_BUILD)
• ☐ 권한 최소화 — 안 쓰는 권한은 심사에서 반려됩니다
• ☐ 개인정보 처리방침 URL · 연령 등급
• ☐ 저사양·구형 기기 실제 테스트
• ☐ 크래시 리포팅 연동 확인 (다음 섹션)
• ☐ 스토어 스크린샷 · 아이콘 (해상도별)

영수증 검증은 서버에서

public PurchaseProcessingResult ProcessPurchase(PurchaseEventArgs e)
{
    // ★ 여기서 바로 아이템을 주지 않습니다
    StartCoroutine(SendToServer(e.purchasedProduct.receipt,
                                e.purchasedProduct.transactionID));
    return PurchaseProcessingResult.Pending;   // 서버 확인 후 완료 처리
}

반드시 지킬 것

• 영수증 검증은 서버에서 — 스토어 서버 API 로 확인
• 중복 지급 방지 — transactionID 를 저장해 두 번 처리하지 않기
• 미완료 거래 복구 — 지급 전에 앱이 꺼지면 다음 실행 때 이어서 처리
• 가격은 스토어에서 받아 표시 — 지역·통화가 다릅니다
• 환불 처리를 설계해 두세요 — 나중에 붙이면 데이터가 꼬입니다

미완료 거래 복구 — 돈 받고 지급 안 되는 사고 막기

// "결제됐는데 아이템이 안 왔어요" — CS 문의 1순위
// 원인: 지급 처리 도중 앱 종료·네트워크 끊김

// 대책 1 — Pending 큐를 로컬에 남긴다
void OnPurchaseConfirmedByStore(string txId, string receipt)
{
    PendingQueue.Add(txId, receipt);     // ① 디스크에 먼저 기록
    TryDeliver(txId);                    // ② 서버 검증 시도
}

// 대책 2 — 앱 시작 때마다 미처리분 재시도
async void Start()
{
    foreach (var p in PendingQueue.All())
    {
        var ok = await Api.VerifyAndGrantAsync(p.TxId, p.Receipt);
        if (ok) PendingQueue.Remove(p.TxId);   // 서버가 중복은 걸러 준다
    }
}

상품 설계 — 심사·정책에 걸리는 지점

원격으로 바꿀 수 있게

// 게임 시작 시 서버에서 설정을 받는다
[Serializable]
public class RemoteConfig
{
    public bool  maintenance;        // 점검 중이면 안내 후 종료
    public string minVersion;        // 이 버전 미만은 강제 업데이트
    public float dropRateMultiplier; // 이벤트 배율
    public bool  adsEnabled;
    public string noticeUrl;
}

async Task BootAsync()
{
    var cfg = await Api.GetConfigAsync();
    if (cfg.maintenance) { ShowMaintenance(); return; }
    if (IsOlder(Application.version, cfg.minVersion)) { ForceUpdate(); return; }
    Balance.Apply(cfg);
}

크래시와 지표

• 크래시 리포팅 — Firebase Crashlytics · Unity Cloud Diagnostics. 심볼 파일 업로드를 빌드에 포함해야 스택이 읽힙니다
• 핵심 지표 — 크래시 없는 사용자 비율(99.5%+ 목표) · 세션 길이 · 이탈 구간
• 퍼널 로그 — 튜토리얼 단계별 이탈률이 가장 많은 것을 알려 줍니다
• A/B 테스트 — 밸런스는 감이 아니라 데이터로

공격 방법과 대응

// 값 하나를 두 벌로 들고 대조 (간단하지만 효과가 있습니다)
public struct SecureInt
{
    private int _value, _check;
    public int Value
    {
        get { if (unchecked(_value * Key) != _check) OnTamper(); return _value; }
        set { _value = value; _check = unchecked(value * Key); }
    }
    private const int Key = 0x5F3F;   // 곱셈 대조 — XOR 와 달리 default(0·0)도 통과합니다
}

현실적인 기준

• 싱글 · 비경쟁 — 최소한의 난독화면 충분합니다. 과투자하지 마세요
• 랭킹 있음 — 점수 계산 근거(플레이 로그)를 서버가 검증
• 실시간 대전 — 서버 권위 필수(🌐 게임 서버 탭 06)
• 이상 탐지 — 통계적으로 불가능한 기록을 자동 플래그

성능 · 안정성

• ☐ 최저 사양 기기에서 30분 연속 플레이 (발열·스로틀링)
• ☐ Profiler 로 GC Alloc 0 B 확인 (전투 중)
• ☐ 씬 전환 10회 반복 후 메모리가 늘지 않는지
• ☐ 네트워크 끊김·비행기 모드에서 앱이 죽지 않는지
• ☐ 백그라운드 전환 → 복귀 시 정상 동작
• ☐ 세이브 파일 손상 시 기본값으로 시작되는지

운영 준비

• ☐ 강제 업데이트·점검 모드 스위치 동작 확인
• ☐ 크래시 리포팅에 심볼 업로드 완료
• ☐ 서버 부하 테스트 완료(예상 동시접속의 3배)
• ☐ 롤백 절차 문서화 — 누가 어떤 명령으로
• ☐ 고객 문의 창구 · 계정 복구 절차
• ☐ 첫 주 모니터링 당번 지정

악의적 시나리오 테스트 — 정상 플레이는 QA 가 아닙니다

• ☐ 결제 승인 화면에서 홈 버튼 → 앱 강제 종료 → 재시작 시 지급 복구되는지
• ☐ 보상 수령 버튼 연타 — 두 번 지급되지 않는지
• ☐ 기기 시계를 내일로 바꾸면 일일 보상이 뚫리는지
• ☐ 튜토리얼 도중 모든 화면에서 종료 → 재시작해도 진행 가능한지
• ☐ 저장 직전 강제 종료 10회 반복 — 세이브 파일이 깨지는지
• ☐ 언어를 아랍어(RTL)·독일어(긴 단어)로 — UI 가 터지는지
• ☐ 알림 권한 거부 상태로 전체 플레이 — 어딘가에서 막히는지

출시 당일 런북 — 미리 적어 두는 대응표

Canvas Scaler — 첫 설정이 전부를 좌우합니다

앵커 · 피벗 실전 규칙

• 구석 UI 는 그 구석에 앵커 — 좌상단 메뉴는 좌상단, 우하단 공격 버튼은 우하단에
• 배경·전체 패널은 Stretch — 네 모서리를 늘려 어떤 비율에서도 빈틈이 없게
• 절대 좌표 배치 금지 — (960, 540) 고정은 다른 해상도에서 반드시 어긋납니다
• 피벗은 "커지는 기준점" — 버튼 펀치 스케일은 (0.5, 0.5), 말풍선은 꼬리 쪽으로
• 중앙 그룹은 빈 오브젝트로 묶어서 그룹째 앵커 — 낱개로 흩어 놓으면 수정할 때 지옥이 됩니다

Safe Area — 노치·펀치홀 대응 코드

// Canvas 바로 아래 "SafeArea" 패널을 하나 두고, 조작 UI 는 전부 그 안에
public class SafeAreaFitter : MonoBehaviour
{
    RectTransform _rt;
    Rect _applied;

    void Awake()  { _rt = (RectTransform)transform; Apply(); }
    void Update() { if (Screen.safeArea != _applied) Apply(); }  // 회전 감지

    void Apply()
    {
        _applied = Screen.safeArea;

        Vector2 min = _applied.position;
        Vector2 max = _applied.position + _applied.size;
        min.x /= Screen.width;   min.y /= Screen.height;   // 픽셀 → 0~1 비율
        max.x /= Screen.width;   max.y /= Screen.height;

        _rt.anchorMin = min;                // 앵커를 Safe Area 에 맞춰 이동
        _rt.anchorMax = max;
        _rt.offsetMin = Vector2.zero;
        _rt.offsetMax = Vector2.zero;
    }
}

테스트 — Device Simulator

• Game 뷰 좌상단에서 Simulator 로 전환 (2021+ 내장, 이전 버전은 패키지 설치)
• 실기기 프리셋으로 노치·펀치홀·Safe Area 가 그대로 재현됩니다
• 최소 확인 세트 — 노치 iPhone · 펀치홀 갤럭시 · 4:3 iPad · 20:9 장폰 네 가지
• 가로 모드는 노치가 좌우로 옵니다 — 왼쪽 끝에 둔 조이스틱이 가려지는지 확인
• 회전을 지원하면 회전 도중에도 UI 가 깨지지 않는지 확인 (위 코드의 Update 감지가 그 대비입니다)

Unity Localization 패키지 — 기본 흐름

• ① Locale 생성 — Window → Asset Management → Localization Tables 에서 ko · en · ja 등록
• ② String Table 생성 — 키(shop_buy)마다 언어별 번역을 한 줄씩
• ③ UI 에 연결 — TMP 텍스트에 Localize String Event 컴포넌트, 또는 아래 코드
• ④ 번역은 CSV 로 내보내 번역가에게 — 스프레드시트 왕복이 실무 표준입니다

using UnityEngine.Localization;
using UnityEngine.Localization.Settings;

// ① 인스펙터에서 테이블·키를 지정하는 방식 (권장)
[SerializeField] LocalizedString buyLabel;    // UI_Table / shop_buy

void OnEnable()  => buyLabel.StringChanged += OnBuyLabel;
void OnDisable() => buyLabel.StringChanged -= OnBuyLabel;   // ★ 해지 (람다로 구독하면 못 뺍니다)
void OnBuyLabel(string t) => _text.text = t;
// 언어를 바꾸면 StringChanged 가 다시 불립니다 — 갱신 코드가 필요 없습니다

// ② 코드에서 직접 — 동적 키·인자 (Smart String: "{0} 획득!")
var s = await LocalizationSettings.StringDatabase
    .GetLocalizedStringAsync("UI_Table", "quest_clear",
        arguments: new object[] { questName }).Task;

// ③ 언어 전환 — 설정 화면에서
LocalizationSettings.SelectedLocale =
    LocalizationSettings.AvailableLocales.Locales[index];

번역 키 설계 원칙

폰트 폴백 — CJK 와 TMP Font Asset

• 언어별 Font Asset 을 만들고 Fallback 체인으로 연결 — 라틴 → 한글 → 일본어 → 중국어 순
• Font Asset 에 없는 글자는 □(두부 글자)로 나옵니다 — 번역 QA 에서 가장 먼저 찾을 것
• CJK 전체를 Static 아틀라스로 구우면 수천 자 × 언어 수만큼 메모리 폭발 — 자주 쓰는 글자만 굽고 나머지는 Dynamic 으로
• 개발 중에는 Dynamic 이 편하지만, 출시 빌드는 Static + Dynamic 폴백 조합이 런타임 히칭을 줄입니다

// 날짜·숫자는 번역이 아니라 CultureInfo 의 일입니다
using System.Globalization;

var culture = CultureInfo.CurrentCulture;      // 기기 언어 설정을 따름

priceText.text = gold.ToString("N0", culture); // 1,234,567 / 1.234.567(독일)
dateText.text  = endTime.ToString("d", culture); // 2026. 8. 11.(한국) / 8/11/2026(미국)

// ★ 저장·서버 통신은 반드시 Invariant — 함정 1순위
//    독일 기기에서 float.Parse("1.5")가 15가 되는 사고를 막습니다
float hp = float.Parse(saved, CultureInfo.InvariantCulture);
string payload = value.ToString(CultureInfo.InvariantCulture);

텍스트가 UI 를 뚫는 문제

• 독일어는 한국어보다 30~40% 깁니다 — 버튼 폭을 한국어 기준으로 잡으면 반드시 뚫립니다
• TMP Auto Size(min~max) 로 줄이되 하한을 정해 가독성을 지키고, 그래도 넘치면 Ellipsis(말줄임)
• 아랍어·히브리어는 RTL(오른쪽→왼쪽) — 지원 계획이 없으면 출시 국가에서 빼는 것도 결정입니다
• Localization 패키지의 Pseudo-Locale 을 켜면 "일부러 길고 이상한 문자"로 전체 UI 를 자동 스트레스 테스트할 수 있습니다

두 개의 Random — 용도가 다릅니다

시드 고정 — 재현 가능한 랜덤

// 데일리 던전 — 전 세계 유저가 같은 날 같은 맵
int seed = int.Parse(DateTime.UtcNow.ToString("yyyyMMdd"));

// ★ 용도별로 스트림을 분리 — 서로 영향을 주지 않게
var mapRng  = new System.Random(seed);
var lootRng = new System.Random(seed ^ 0x5EED);
var aiRng   = new System.Random(seed ^ 0x0A1);

// 버그 제보 대응 — 생성 때 쓴 시드를 로그·세이브에 남긴다
Debug.Log($"[MapGen] seed={seed}");
// → "이상한 맵이 나왔어요" 제보에 시드만 받으면 즉시 재현됩니다

가중치 뽑기 — 가챠 확률표

// 확률표는 기획 데이터 — 합이 100 이 아니어도 동작합니다
static readonly (string id, float w)[] Table =
{
    ("SSR", 1.5f), ("SR", 8.5f), ("R", 30f), ("N", 60f)
};

public static string Pick(System.Random rng)
{
    float total = 0f;
    foreach (var e in Table) total += e.w;

    double r = rng.NextDouble() * total;   // 0 ≤ r < total
    foreach (var e in Table)
    {
        r -= e.w;
        if (r < 0) return e.id;
    }
    return Table[Table.Length - 1].id;     // 부동소수 오차 대비
}

셔플 — Fisher-Yates 가 유일한 정답

public static void Shuffle<T>(IList<T> list, System.Random rng)
{
    for (int i = list.Count - 1; i > 0; i--)
    {
        int j = rng.Next(i + 1);           // ★ 0..i "포함" — i 로 쓰면 편향
        (list[i], list[j]) = (list[j], list[i]);
    }
}

// 카드 덱 — 한 번 섞고 위에서 뽑으면 "중복 없는 랜덤"이 공짜
Shuffle(deck, rng);
var hand = deck.Take(5);

맵 생성 입문 — 그리드 랜덤워크

// 64×64 그리드에 방 120칸짜리 동굴 파기 — 가장 단순한 절차적 맵
bool[,] map = new bool[64, 64];
var rng = new System.Random(seed);
int x = 32, y = 32, carved = 0;

while (carved < 120)
{
    if (!map[x, y]) { map[x, y] = true; carved++; }
    switch (rng.Next(4))                   // 상하좌우 랜덤 이동
    {
        case 0: x = Math.Min(x + 1, 62); break;
        case 1: x = Math.Max(x - 1, 1);  break;
        case 2: y = Math.Min(y + 1, 62); break;
        case 3: y = Math.Max(y - 1, 1);  break;
    }
}
// 같은 seed → 언제나 같은 맵. 여기서 셀룰러 오토마타·BSP 로 발전합니다

랜덤워크는 반드시 이어진 동굴이 나온다는 것이 장점입니다 — 입문은 여기서 시작해 방 배치(BSP)·매끈한 동굴(셀룰러 오토마타)로 넓혀 가세요.

서버 검증과 시드 공유 — 치트 방지 연결

• 서버가 시드를 발급 — 던전 입장 때 시드를 주고 클라이언트가 맵·드랍을 생성
• 클리어 보고 때 서버가 같은 시드로 재계산 — 드랍 결과가 다르면 조작입니다
• 클라이언트가 시드를 고를 수 있으면 "좋은 시드"만 골라 리세마라합니다 — 발급은 반드시 서버가
• 데일리 콘텐츠 랭킹은 같은 시드 = 같은 조건이라 공정성 시비가 사라집니다

히트스톱 — 타격의 0.05초

// 타격 순간 시간을 잠깐 멈춰 "박히는 느낌"을 만듭니다
public class HitStop : MonoBehaviour
{
    static Coroutine s_run;

    public static void Play(MonoBehaviour host, float dur = 0.05f)
    {
        if (s_run != null) return;                 // 중첩 방지
        s_run = host.StartCoroutine(Run(dur));
    }

    static IEnumerator Run(float dur)
    {
        Time.timeScale = 0.05f;
        yield return new WaitForSecondsRealtime(dur);  // ★ Realtime 필수
        Time.timeScale = 1f;
        s_run = null;
    }
}

화면 흔들림은 카메라 좌표를 직접 만지지 말고 Cinemachine Impulse 로 — 추적·연출과 충돌하지 않고 감쇠도 공짜입니다.

DOTween 실전 — UI 가 살아나는 세 가지

// ① 버튼 눌림 — 펀치 스케일
button.transform.DOPunchScale(Vector3.one * 0.12f, 0.25f, vibrato: 6)
      .SetUpdate(true);          // ★ 일시정지(timeScale 0) 중에도 동작

// ② 팝업 열기 — 스케일 + 페이드
popup.transform.DOScale(1f, 0.25f).From(0.85f).SetEase(Ease.OutBack);
popupGroup.DOFade(1f, 0.2f).From(0f);

// ③ 데미지 텍스트 — 떠오르며 사라짐
DOTween.Sequence()
    .Append(txt.transform.DOMoveY(pos.y + 0.8f, 0.5f))
    .Join(txt.DOFade(0f, 0.35f).SetDelay(0.15f))
    .SetLink(txt.gameObject);    // ★ 오브젝트 파괴 시 트윈도 자동 정리

코요테 타임 · 입력 버퍼 — 플랫포머 관용

[SerializeField] float coyoteTime = 0.1f;   // 발판을 벗어나도 잠깐 점프 허용
[SerializeField] float bufferTime = 0.15f;  // 착지 직전 입력을 기억해 두기

float _coyote, _buffer;

void Update()
{
    _coyote = IsGrounded()   ? coyoteTime : _coyote - Time.deltaTime;
    _buffer = JumpPressed()  ? bufferTime : _buffer - Time.deltaTime;

    if (_coyote > 0f && _buffer > 0f)
    {
        _coyote = 0f; _buffer = 0f;        // ★ 소모 처리 — 이중 점프 방지
        Jump();
    }
}

"조작이 구리다"는 리뷰의 절반은 이 두 값이 0 이라서입니다. 엄격한 판정은 정확한 게 아니라 야박한 것입니다 — 유저의 의도를 0.1초만 관대하게 읽어 주면 같은 게임이 다르게 느껴집니다.

접근성 — 옵션 몇 개가 유저를 넓힙니다

세 가지 구조

직접 만들 것인가

무엇을 어디로 보낼 것인가

신뢰성 UDP 의 최소 구성

// 헤더에 번호와 확인용 비트를 실어 보낸다 (라이브러리가 해 주는 일)
[StructLayout(LayoutKind.Sequential, Pack = 1)]
struct Header
{
    public ushort Seq;        // 이 패킷의 번호
    public ushort Ack;        // 내가 마지막으로 받은 번호
    public uint   AckBits;    // 그 앞 32개를 받았는지 비트로
    public byte   Channel;    // 0=비신뢰 1=신뢰 2=순서보장
}

• 재전송 — Ack 가 안 오면 다시 보냅니다(신뢰 채널만)
• 순서 — 필요할 때만 (전부 순서를 지키면 TCP 와 같아집니다)
• 조각화 — MTU(약 1200바이트)를 넘으면 나눠 보냅니다
• 혼잡 제어 — 손실률이 높으면 전송 주기를 낮춥니다

TCP 수신 루프

var listener = new TcpListener(IPAddress.Any, 7777);
listener.Start(backlog: 512);

while (!ct.IsCancellationRequested)
{
    var client = await listener.AcceptTcpClientAsync(ct);
    client.NoDelay = true;                 // ★ Nagle 끄기 (지연 40ms 제거)
    _ = HandleAsync(client, ct);           // 세션마다 독립 처리
}

static async Task HandleAsync(TcpClient c, CancellationToken ct)
{
    var buf = ArrayPool<byte>.Shared.Rent(4 + 64 * 1024);   // ★ 헤더 + 최대 메시지가 들어가야 함
    try
    {
        var stream = c.GetStream();
        var filled = 0;
        while (true)
        {
            var n = await stream.ReadAsync(buf.AsMemory(filled), ct);
            if (n == 0) break;             // 연결 종료
            filled += n;

            // ★ TCP 는 '메시지 경계'가 없다 — 길이 헤더로 잘라야 한다
            var offset = 0;
            while (filled - offset >= 4)
            {
                var len = BinaryPrimitives.ReadInt32LittleEndian(
                              buf.AsSpan(offset));
                if (len <= 0 || len > 64 * 1024) throw new InvalidDataException();
                if (filled - offset - 4 < len) break;      // 아직 덜 왔다
                Dispatch(buf.AsSpan(offset + 4, len));
                offset += 4 + len;
            }
            Buffer.BlockCopy(buf, offset, buf, 0, filled - offset);
            filled -= offset;
        }
    }
    finally { ArrayPool<byte>.Shared.Return(buf); c.Dispose(); }
}

반드시 챙길 것

• 메시지 경계 — TCP 는 스트림입니다. 길이 헤더로 직접 자르세요. 이걸 빼먹으면 "가끔 패킷이 깨진다" 가 됩니다
• 길이 상한 — 헤더의 길이를 그대로 믿고 버퍼를 잡으면 메모리 폭탄 공격에 당합니다
• NoDelay = true — 안 켜면 작은 패킷이 40ms 씩 지연됩니다
• 연결 상한 · 유휴 타임아웃 — 접속만 하고 아무것도 안 하는 연결을 끊으세요
• ArrayPool — 세션마다 버퍼를 새로 잡으면 GC 가 무너집니다

패킷 정의

// 공용 프로젝트에 두고 클라이언트·서버가 함께 참조합니다
public enum PacketId : ushort
{
    None = 0,
    C_Move = 1, C_Fire = 2, C_Chat = 3,
    S_Spawn = 100, S_State = 101, S_Hit = 102,
}

[MessagePackObject]
public struct MovePacket
{
    [Key(0)] public uint  Tick;      // ★ 시간 기준 (뒤에서 씁니다)
    [Key(1)] public short X, Y;      // 좌표를 정수로 압축 (cm 단위)
    [Key(2)] public byte  YawDeg;    // 회전은 1바이트로 충분
    [Key(3)] public byte  Flags;     // 점프·달리기 등을 비트로
}

• float 대신 정수 — 위치를 cm 단위 short 로 담으면 4바이트→2바이트
• 불리언은 비트로 — 8개를 1바이트에
• 변하지 않는 값은 보내지 않기 — 처음 한 번만
• 델타 압축 — 직전과 같으면 생략

보내는 양 줄이기

// ① 관심 영역(AOI) — 내 주변만 보낸다
foreach (var viewer in room.Players)
{
    var near = room.Grid.Query(viewer.Pos, radius: 30f);   // 격자 검색
    viewer.Send(BuildState(near));      // 전체가 아니라 주변 것만
}

// ② 우선순위 — 가까운 것은 자주, 먼 것은 가끔
var rate = dist < 10 ? 20 : dist < 30 ? 10 : 3;   // Hz

// ③ 묶어 보내기 — 작은 패킷 여러 개보다 한 번에
_batch.Add(packet);
if (_batch.Count >= 16 || _timer > 0.05f) FlushBatch();

룸 하나 = 스레드 하나

public sealed class GameRoom
{
    private readonly Channel<IPacket> _inbox =
        Channel.CreateUnbounded<IPacket>(new() { SingleReader = true });

    public ValueTask PushAsync(IPacket p) => _inbox.Writer.WriteAsync(p);

    public async Task RunAsync(CancellationToken ct)
    {
        var tick = TimeSpan.FromMilliseconds(50);      // 20Hz
        var next = DateTime.UtcNow;

        while (!ct.IsCancellationRequested)
        {
            // ① 들어온 입력을 전부 처리 (이 룸의 데이터는 나만 만진다 → 락 불필요)
            while (_inbox.Reader.TryRead(out var p)) Handle(p);

            // ② 게임 로직 한 틱
            Simulate((float)tick.TotalSeconds);

            // ③ 상태 방송
            Broadcast();

            next += tick;
            var wait = next - DateTime.UtcNow;
            if (wait > TimeSpan.Zero) await Task.Delay(wait, ct);
            else next = DateTime.UtcNow;               // 밀렸으면 따라잡지 않는다
        }
    }
}

이 구조의 장점

• 락이 사라집니다 — 룸 데이터는 그 루프만 만집니다
• 재현이 쉽습니다 — 입력 순서가 정해져 있어 버그 재현이 가능합니다
• 수평 확장이 자연스럽습니다 — 룸을 다른 서버로 옮기면 됩니다
• 틱 시간을 측정해 룸당 부하를 바로 알 수 있습니다

// 저장은 비동기로 흘려보낸다
_saveQueue.Enqueue(new SaveJob(playerId, snapshot));

// 세션 정리 — 끊긴 연결을 방치하면 룸이 안 닫힙니다
if (now - p.LastPacketAt > TimeSpan.FromSeconds(20)) Kick(p, "timeout");

무엇을 보내야 하는가

// "나 (100, 50)으로 이동했어"
Send(new Move { X = 100, Y = 50 });
// "적에게 9999 데미지 줬어"
Send(new Hit { Dmg = 9999 });
// → 메모리 수정 한 번이면 끝

// "앞으로 가려고 함"
Send(new Input { Dir = 1, Tick = t });
// "이 방향으로 쐈음"
Send(new Fire { Dir = d, Tick = t });
// → 결과는 서버가 계산

// 서버: 입력을 받아 직접 계산하고 검증한다
void OnInput(Player p, InputPacket input)
{
    // ① 시간 검증 — 미래·과거 입력은 버린다
    if (input.Tick > _tick + 2 || input.Tick < _tick - 20) return;

    // ② 이동은 서버가 계산 (속도 상한 적용)
    var move = Clamp(input.Dir, p.MaxSpeed) * DeltaTime;
    var next = p.Pos + move;

    // ③ 지형 충돌도 서버가 판정
    if (!_map.IsWalkable(next)) return;

    p.Pos = next;
}

검증 항목

• 이동 속도 — 두 틱 사이 이동 거리가 상한을 넘으면 거부
• 쿨타임 — 스킬 사용 간격을 서버가 기록
• 사거리·시야 — 벽 너머의 적을 맞힐 수 없게
• 데미지 — 공식은 서버에만. 클라이언트는 표시만
• 인벤토리 — 가진 적 없는 아이템 사용 차단
• 입력 빈도 — 초당 입력 수 상한 (자동 연사 매크로)

예측과 재조정

// 클라이언트 — 보낸 입력을 기억해 둔다
private readonly Queue<PendingInput> _pending = new();

void SendInput(InputPacket input)
{
    _pending.Enqueue(new PendingInput(input, _tick));
    ApplyLocally(input);                 // ★ 서버를 기다리지 않고 바로 움직임
    net.Send(input);
}

// 서버 상태가 도착하면
void OnServerState(StatePacket s)
{
    // 서버가 확인해 준 입력까지는 버린다
    while (_pending.Count > 0 && _pending.Peek().Tick <= s.LastProcessedTick)
        _pending.Dequeue();

    if (Vector3.Distance(transform.position, s.Pos) > 0.05f)
    {
        transform.position = s.Pos;                 // 서버 위치로 되돌리고
        foreach (var p in _pending) ApplyLocally(p.Input);   // 남은 입력을 다시 적용
    }
}

보간과 지연 보상

// ① 다른 플레이어 — 받은 상태 두 개 사이를 보간
const float InterpDelay = 0.1f;          // 100ms 뒤처져 그린다

var renderTime = Now - InterpDelay;
var (a, b) = _buffer.Around(renderTime);
transform.position = Vector3.Lerp(a.Pos, b.Pos,
    (renderTime - a.Time) / (b.Time - a.Time));

// ② 지연 보상 — 쏜 시점의 과거로 되돌려 판정 (히트스캔)
bool Hit(Player shooter, Ray ray, uint clientTick)
{
    var rewind = _history.Snapshot(clientTick);       // 그때의 모든 위치
    return rewind.Raycast(ray, out var target);
}

기본 구조

public sealed class MatchMaker
{
    private readonly List<Ticket> _queue = new();

    public void Enqueue(Ticket t) { lock (_queue) _queue.Add(t); }

    // 주기적으로 돌며 짝을 맞춘다
    public void Tick()
    {
        lock (_queue)
        {
            _queue.Sort((a, b) => a.Rating.CompareTo(b.Rating));

            for (int i = 0; i + 1 < _queue.Count; )
            {
                var (a, b) = (_queue[i], _queue[i + 1]);
                // ★ 기다린 시간만큼 실력 허용 범위를 넓힌다
                var band = 50 + a.WaitSeconds * 20;

                if (Math.Abs(a.Rating - b.Rating) <= band)
                {
                    CreateRoom(a, b);
                    _queue.RemoveRange(i, 2);
                }
                else i++;
            }
        }
    }
}

현실에서 고려할 것

• 지역(핑) — 실력보다 지연이 경험을 더 망칩니다. 지역별 큐가 기본
• 대기 시간 상한 — 오래 기다리면 조건을 풀어 주세요. 3분은 이탈입니다
• 파티 — 인원이 다른 그룹을 섞는 규칙이 필요합니다
• 재접속 — 끊긴 사람이 돌아올 자리를 남겨 둘지
• 봇 투입 — 새벽처럼 사람이 적을 때
• 신규 보호 — 초반 몇 판은 쉬운 상대와

비교

// Netcode 예 — 서버에게 요청하고(RPC), 상태는 자동 동기화
public class PlayerNet : NetworkBehaviour
{
    private NetworkVariable<int> _hp = new(100,
        NetworkVariableReadPermission.Everyone,
        NetworkVariableWritePermission.Server);       // ★ 서버만 쓰기

    [Rpc(SendTo.Server)]
    public void FireRpc(Vector3 dir)
    {
        if (!IsServer) return;
        if (Time.time - _lastFire < 0.2f) return;     // 서버가 쿨타임 검증
        _lastFire = Time.time;
        SpawnBullet(dir);
    }
}

고를 때 확인할 것

• 전용 서버(헤드리스) 지원 — Listen 서버만 되면 경쟁 게임에 못 씁니다
• 비용 모델 — CCU 과금은 성공할수록 부담이 커집니다. 미리 계산해 보세요
• 예측·지연 보상 내장 여부 — 직접 구현하려면 몇 달입니다
• 재접속·룸 이전 지원
• 플랫폼 — 콘솔 인증 지원 여부

랭킹 — Redis Sorted Set

// 점수 갱신 (O(log n))
await db.SortedSetAddAsync("rank:season3", playerId, score);

// 내 순위 (0부터, 랭킹에 없으면 null)
var rank = await db.SortedSetRankAsync("rank:season3", playerId, Order.Descending);

// 상위 100명
var top = await db.SortedSetRangeByRankWithScoresAsync(
              "rank:season3", 0, 99, Order.Descending);

// 내 주변 순위 (앞뒤 5명) — 음수 인덱스는 "끝에서부터"라 0 에서 자릅니다
if (rank is long r)
{
    var around = await db.SortedSetRangeByRankAsync(
                  "rank:season3", Math.Max(0, r - 5), r + 5, Order.Descending);
}

채팅 — 서버 간 전달

// 서버가 여러 대면 Redis Pub/Sub 으로 이어 준다
await sub.SubscribeAsync("chat:global", (_, msg) =>
{
    var m = JsonSerializer.Deserialize<ChatMsg>(msg!);
    hub.Clients.Group("global").SendAsync("Chat", m);   // 내 서버 접속자에게
});

public async Task SendGlobal(ChatMsg m)
{
    if (!_rateLimit.TryConsume(m.SenderId)) return;     // 도배 방지
    m.Text = _filter.Mask(m.Text);                      // 금칙어
    await pub.PublishAsync("chat:global", JsonSerializer.Serialize(m));
}

• 도배 제한 — 초당 1~2회, 같은 문장 반복 차단
• 금칙어·신고 — 운영 도구가 반드시 필요합니다
• 로그 보관 — 분쟁 시 근거. 보관 기간을 정책으로 명시
• 차단 목록 — 서버에서 필터링(클라이언트 차단은 우회됩니다)

봇 클라이언트

// 실제 프로토콜을 그대로 쓰는 가짜 클라이언트
static async Task RunBotAsync(int id, CancellationToken ct)
{
    using var cli = new GameClient();
    await cli.ConnectAsync(host, port, ct);
    await cli.LoginAsync($"bot{id}", ct);
    await cli.JoinRandomRoomAsync(ct);

    var rnd = new Random(id);
    while (!ct.IsCancellationRequested)
    {
        await cli.SendInputAsync(new Input {
            Dir = rnd.Next(0, 8), Fire = rnd.Next(10) == 0 }, ct);
        await Task.Delay(50, ct);                 // 20Hz
    }
}

// 동시에 띄우기 — 한 프로세스에서 수천 개도 가능합니다
// ★ 봇은 끝나지 않는 루프라 Parallel.ForEachAsync(동시 200 제한)로 돌리면
//   앞의 200개만 영원히 돌고 나머지는 시작도 못 합니다 — 전부 한꺼번에 띄웁니다
await Task.WhenAll(Enumerable.Range(0, 5000).Select(i => RunBotAsync(i, ct)));

무엇을 볼 것인가

• 틱 시간 — 20Hz 라면 50ms 를 넘는 순간이 언제부터인지
• CPU · GC — Gen2 수집이 잦아지면 설계 문제입니다
• 대역폭 — 인당 KB/s × CCU = 월 트래픽 비용
• 접속 폭주 — 오픈 직후 동시에 몰리는 상황을 따로 테스트
• 재접속 폭풍 — 서버를 껐다 켰을 때 전원이 동시에 붙습니다

봇을 제대로 만들기 — 실제와 같아야 의미가 있습니다

// 봇은 "실제 사용자 행동"을 흉내 내야 합니다
// 모두가 같은 방에 들어가 같은 입력을 보내면 캐시가 100% 적중해
// 실제보다 훨씬 좋은 숫자가 나옵니다 — 가장 흔한 실수입니다

static async Task RunBotAsync(int id, ScenarioConfig cfg, CancellationToken ct)
{
    var rnd = new Random(id);                    // ★ 봇마다 다른 시드

    // ① 접속 타이밍을 흩뿌린다 (실제 사용자는 동시에 안 옵니다)
    await Task.Delay(rnd.Next(0, cfg.RampUpMs), ct);

    using var cli = new GameClient();
    var sw = Stopwatch.StartNew();
    await cli.ConnectAsync(cfg.Host, cfg.Port, ct);
    Metrics.ConnectMs.Record(sw.Elapsed.TotalMilliseconds);

    await cli.LoginAsync($"bot{id}", ct);

    while (!ct.IsCancellationRequested)
    {
        // ② 행동 분포를 실제 로그에서 뽑아 씁니다
        var roll = rnd.NextDouble();
        if (roll < 0.60)      await PlayMatchAsync(cli, rnd, ct);   // 60% 전투
        else if (roll < 0.80) await BrowseShopAsync(cli, ct);       // 20% 상점
        else if (roll < 0.92) await CheckMailAsync(cli, ct);        // 12% 우편
        else                  await ViewRankingAsync(cli, ct);      //  8% 랭킹

        // ③ 생각하는 시간 — 없으면 실제보다 10배 부하가 됩니다
        await Task.Delay(rnd.Next(2000, 8000), ct);
    }
}

static async Task PlayMatchAsync(GameClient cli, Random rnd, CancellationToken ct)
{
    await cli.JoinRandomRoomAsync(ct);
    var end = DateTime.UtcNow.AddMinutes(3);
    while (DateTime.UtcNow < end && !ct.IsCancellationRequested)
    {
        var t0 = Stopwatch.GetTimestamp();
        await cli.SendInputAsync(new Input {
            Dir = rnd.Next(0, 8), Fire = rnd.Next(10) == 0 }, ct);
        Metrics.InputRtt.Record(Stopwatch.GetElapsedTime(t0).TotalMilliseconds);
        await Task.Delay(50, ct);                // 20Hz
    }
    await cli.LeaveRoomAsync(ct);
}

무엇을 재고 어떻게 읽나

결과를 읽는 법 — 실제 예시

  CCU     틱p99   RTTp99   CPU   Gen2/분   판정
  1,000    12ms    38ms    18%     0.1     여유
  3,000    18ms    52ms    41%     0.3     정상
  5,000    31ms    78ms    63%     0.8     정상
  7,000    47ms   140ms    78%     2.4     ★ 주의 — 틱이 주기(50ms)에 근접
  8,000   112ms   380ms    82%     6.1     붕괴 시작
  9,000   340ms   900ms    85%    11.0     사실상 서비스 불가

  → 안전 운영선은 5,000. 7,000 이 한계.
    CPU 는 82% 밖에 안 되는데 무너졌다는 것에 주목하세요.
    범인은 CPU 가 아니라 GC 입니다 (Gen2 가 0.8 → 6.1 로 급증).
    이 서버는 증설이 아니라 "루프에서 할당 없애기"가 답입니다.

• 평균은 거짓말을 합니다 — 평균 20ms 라도 p99 가 200ms 면 100명 중 1명은 매 순간 렉을 겪습니다. 항상 p95·p99 로 판단하세요
• 무너지기 직전 구간이 가장 중요한 정보입니다. "몇 명까지 되나"보다 "어떤 지표가 먼저 나빠졌나"가 개선 방향을 알려 줍니다
• 테스트마다 커밋 해시와 설정을 함께 기록하세요. 나중에 "언제부터 나빠졌나"를 추적할 수 있는 유일한 방법입니다
• CI 에 가벼운 부하 테스트를 넣으세요 — 소규모(500 CCU · 3분)라도 성능 회귀를 배포 전에 잡습니다
• 일반 REST API 는 k6·NBomber 로 충분합니다. 게임 프로토콜(UDP·커스텀 바이너리)은 직접 만든 봇 외에 방법이 없습니다

최소한의 준비

• 주기적 스냅샷 — 룸 상태를 30초마다 저장해 두면 재시작 시 복구 가능
• 재접속 유예 — 끊겨도 60초간 자리를 유지
• 점검 모드 — 새 접속만 막고 진행 중인 판은 끝내게(드레인)
• 버전 게이트 — 구버전 클라이언트 접속 차단
• 보상 지급 도구 — 장애 후 우편으로 일괄 지급

// 그레이스풀 셧다운 — 진행 중인 방을 끝내고 종료
app.Lifetime.ApplicationStopping.Register(() =>
{
    _matchMaker.StopAccepting();                  // 새 매칭 중단
    foreach (var room in _rooms) room.NotifyShutdown(seconds: 60);
    _drainCompleted.Wait(TimeSpan.FromSeconds(90));
});
// ★ 컨테이너라면 종료 유예(k8s terminationGracePeriodSeconds 기본 30초)를
//   90초보다 길게 — 아니면 드레인 도중 강제 종료됩니다

관측

// 게임 서버 고유 지표를 반드시 내보내세요
static readonly Meter Meter = new("Game.Server");
static readonly Histogram<double> TickMs =
    Meter.CreateHistogram<double>("room.tick.ms");
static readonly UpDownCounter<int> Ccu =
    Meter.CreateUpDownCounter<int>("player.ccu");

var sw = Stopwatch.StartNew();
Simulate(dt);
TickMs.Record(sw.Elapsed.TotalMilliseconds,
              new KeyValuePair<string, object?>("room", room.Mode));

왜 raw TCP 가 아니라 WebSocket 인가

• 브라우저에서 쓸 수 있는 유일한 소켓입니다 — 웹 게임·WebGL 빌드는 raw TCP/UDP 를 열 방법 자체가 없습니다
• 방화벽·프록시를 통과합니다 — 443 포트의 HTTPS 로 시작해 업그레이드되므로 회사·학교 망에서도 막히지 않습니다
• 메시지 경계를 프로토콜이 지켜 줍니다 — raw TCP 처럼 길이 헤더로 직접 자르는 코드(03 섹션)가 필요 없습니다
• TLS 가 공짜에 가깝습니다 — wss:// 는 기존 HTTPS 인증서·인프라를 그대로 씁니다

ASP.NET Core 최소 구현

var app = WebApplication.CreateBuilder(args).Build();

app.UseWebSockets(new WebSocketOptions
{
    KeepAliveInterval = TimeSpan.FromSeconds(15),   // 프로토콜 핑을 대신 보내 줌
});

app.Map("/ws", async (HttpContext ctx) =>
{
    if (!ctx.WebSockets.IsWebSocketRequest)
    { ctx.Response.StatusCode = 400; return; }

    // ★ 업그레이드 전에 인증 — 헤더를 못 붙이는 클라가 있어 쿼리스트링으로
    var player = await AuthAsync(ctx.Request.Query["access_token"]);
    if (player is null) { ctx.Response.StatusCode = 401; return; }

    using var ws = await ctx.WebSockets.AcceptWebSocketAsync();
    var buf = new byte[16 * 1024];

    try
    {
        while (ws.State == WebSocketState.Open)
        {
            var r = await ws.ReceiveAsync(buf.AsMemory(), ctx.RequestAborted);
            if (r.MessageType == WebSocketMessageType.Close) break;
            if (!r.EndOfMessage)                 // ★ 큰 메시지는 조각나서 온다
                throw new InvalidDataException("메시지 상한 초과");

            // ★ 복사해서 넘깁니다 — buf 는 다음 수신에 덮어씌워집니다
            await _room.PushAsync(player, buf.AsSpan(0, r.Count).ToArray());
        }
    }
    finally
    {
        await _room.LeaveAsync(player);      // 예외로 끊겨도 반드시 정리
    }
});

app.Run();

메시지 프레이밍 — 텍스트로 시작

// ① 텍스트(JSON) — 디버깅이 쉽다. 캐주얼 게임은 대부분 이걸로 충분
await ws.SendAsync(JsonSerializer.SerializeToUtf8Bytes(
        new { type = "move", x, y, tick }),
    WebSocketMessageType.Text, endOfMessage: true, ct);

// ② 바이너리(MessagePack) — 같은 내용이 1/3 크기. 트래픽이 커지면 전환
await ws.SendAsync(MessagePackSerializer.Serialize(new MovePacket(x, y, tick)),
    WebSocketMessageType.Binary, true, ct);

• type 필드를 반드시 — 메시지 종류를 구분할 유일한 수단입니다. 04 섹션의 PacketId 와 같은 역할입니다
• 텍스트 프레임은 브라우저 개발자 도구에 내용이 그대로 보입니다 — 개발 속도가 완전히 다릅니다
• 전환 기준은 감이 아니라 대역폭 청구서입니다 — 인당 KB/s × CCU 를 계산해 보고 바꾸세요

하트비트 · 재접속

// 프로토콜 핑만 믿지 말고 앱 레벨 하트비트를 따로 둡니다
// (중간 장비가 핑에 대신 응답해 '죽은 연결'이 살아 보일 수 있습니다)
if (now - s.LastMsgAt > TimeSpan.FromSeconds(30))
    await s.CloseAsync(WebSocketCloseStatus.NormalClosure, "timeout", ct);

// 재접속 — 새 연결에 이전 세션을 이어 붙인다
var resume = ctx.Request.Query["session"];
var session = _sessions.TryResume(resume, out var old)
    ? old                          // ★ 60초 안에 돌아오면 방·상태 그대로
    : _sessions.Create(player);

• 모바일에서 끊김은 일상입니다 — 화면 잠금·지하철. 재접속 유예 없이 방에서 빼면 항의가 옵니다
• 재접속 직후 전체 상태 스냅샷을 한 번 보내고 그 뒤부터 증분으로 — 놓친 것 복구를 클라가 고민하지 않게
• 클라이언트 재시도는 지수 백오프(1·2·4·8초)로 — 서버 복구 순간의 재접속 폭풍(11 섹션)을 줄입니다

고정 시간 스텝 — 서버 틱의 표준형

// 시뮬레이션 dt 를 항상 같게 — 같은 입력이면 같은 결과가 됩니다
const double FixedDt = 1.0 / 20;                  // 20Hz = 50ms
var acc  = 0.0;
var prev = Stopwatch.GetTimestamp();

while (!ct.IsCancellationRequested)
{
    var now = Stopwatch.GetTimestamp();
    acc += Stopwatch.GetElapsedTime(prev, now).TotalSeconds;
    prev = now;

    while (acc >= FixedDt)                        // 밀린 만큼 따라잡는다
    {
        Simulate(FixedDt);  _tick++;              // ★ dt 는 절대 변하지 않음
        acc -= FixedDt;

        if (acc >= FixedDt * 5)                   // ★ 죽음의 나선 방지
        { acc = 0; _log.Warn("틱 5개 이상 밀림 — 버림"); break; }
    }

    Broadcast();
    await Task.Delay(1, ct);                      // CPU 양보
}

클라 - 서버 시간 오프셋 — 핑퐁으로

// 클라이언트 — 여러 번 재서 중앙값을 쓴다
async Task SyncClockAsync()
{
    var samples = new List<double>();
    for (var i = 0; i < 8; i++)
    {
        var t0 = LocalMs();
        var serverMs = await PingAsync();      // 서버가 자기 시각을 돌려줌
        var t1 = LocalMs();

        var rtt = t1 - t0;
        // ★ 편도 ≈ RTT / 2 로 가정 — 서버 시각 + 편도 = 지금의 서버 시각
        samples.Add(serverMs + rtt / 2 - t1);
        await Task.Delay(50);
    }
    samples.Sort();
    _offset = samples[samples.Count / 2];      // 중앙값 — 튄 표본 제거
}

double ServerNowMs() => LocalMs() + _offset;   // 이후 모든 시간 판정에 이것을

• 기기 시계를 신뢰하지 마세요 — 사용자 폰의 DateTime.Now 는 몇 분씩 틀립니다. 항상 오프셋 보정값을 씁니다
• 주기적으로 다시 잽니다 — 기기 시계는 흐르면서 조금씩 어긋납니다. 접속 시 + 몇 분마다 한 번이면 충분합니다
• 회선이 비대칭이면 RTT/2 가정이 틀어집니다 — RTT 가 가장 작은 표본이 가장 정확한 표본입니다

지연 시간 예산 — 키 입력이 화면에 오기까지

틱이 밀릴 때 (오버런)

• 증상 — 한 틱 처리가 주기(50ms)를 넘으면 다음 틱이 늦고, 밀린 틱을 따라잡느라 더 밀리는 죽음의 나선이 시작됩니다
• 1차 방어 — 위 코드처럼 밀린 틱 상한(5개)을 두고 넘으면 버립니다. 게임이 잠깐 느려지는 쪽이 서버가 영원히 못 따라잡는 쪽보다 낫습니다
• 원인 추적 — 틱 시간 p99 를 상시 기록(11 섹션). 범인은 대부분 루프 안의 할당(GC)과 동기 I/O 입니다
• 구조적 해법 — 룸당 인원 상한 · AOI(04 섹션) · 무거운 계산을 여러 틱에 나눠 실행

① 턴제 · 비동기 — 수집형 RPG

• 다른 플레이어와 같은 순간에 있을 필요가 없는 게임 전부 — 수집형 RPG · 방치형 · 퍼즐
• 비동기 PvP(방어덱 침공)도 상대 데이터를 읽어 올 뿐입니다 — 실시간이 아닙니다
• 국내 매출 상위권의 상당수가 이 구조입니다. 실시간 서버 없이도 대작이 됩니다

② 실시간 룸 기반 — 대전 · 파티

• MOBA · 대전 액션 · 배틀로얄 · 파티 게임 — 판(세션)의 시작과 끝이 명확한 게임
• 룸 상태는 메모리에만 있다 사라집니다 — 저장할 게 없어서 수평 확장이 쉽습니다
• 룸 서버의 증설·회수는 오케스트레이터에 맡깁니다(09 섹션)

③ MMO형 — 영속 세계

• 룸과 달리 세계가 끝나지 않습니다 — 상태를 계속 저장해야 하고, 함부로 내릴 수도 없습니다
• 존 경계에서의 전투, 이관 도중의 아이템 복사 버그가 이 구조의 악명 높은 함정입니다
• 전담 서버팀 없이 시도하지 마세요 — ①②와는 난이도의 차원이 다릅니다

우리 게임은 어디인가 — 판정 기준

• 상대의 행동을 언제 봐야 하나? — 다음 접속 때 → ①, 1초 안에 → ②, 같은 공간에 수백 명 → ③
• "한 판"이 있는가? — 시작과 끝이 있으면 ②, 세계가 계속 흐르면 ③
• 끊겼다 들어와도 되는가? — 된다면 ① 쪽으로 당길 수 있습니다
• 애매하면 낮은 번호로 — ① 에서 ② 로 넓히기는 되지만, 반대는 재설계입니다

첫 API

dotnet new webapi -o GameApi --use-minimal-apis
cd GameApi && dotnet run

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();                  // 문서 자동 생성
var app = builder.Build();

if (app.Environment.IsDevelopment()) app.MapOpenApi();

app.MapGet("/health", () => Results.Ok(new { status = "ok" }));

app.MapGet("/players/{id:int}", async (int id, IPlayerRepo repo) =>
    await repo.FindAsync(id) is {} p
        ? Results.Ok(p)
        : Results.NotFound());

app.MapPost("/players", async (CreatePlayerDto dto, IPlayerRepo repo) =>
{
    var p = await repo.CreateAsync(dto.Name);
    return Results.Created($"/players/{p.Id}", p);
});

app.Run();

커지면 나눈다

// 기능별로 확장 메서드 하나씩
public static class PlayerEndpoints
{
    public static IEndpointRouteBuilder MapPlayers(this IEndpointRouteBuilder app)
    {
        var g = app.MapGroup("/players")
                   .RequireAuthorization()
                   .WithTags("Player");

        g.MapGet("/{id:int}", GetAsync);
        g.MapPost("/", CreateAsync);
        return app;
    }
}

// Program.cs 는 조립만
app.MapPlayers().MapShop().MapRanking();

Program.cs 미들웨어 순서

var app = builder.Build();

app.UseExceptionHandler("/error");   // 1. 가장 바깥 — 아래 전부를 감싼다
app.UseHsts();                       // 2. 브라우저에 "https 로만 와라"
app.UseHttpsRedirection();           // 3. http → https
app.UseStaticFiles();                // 4. 정적 파일은 여기서 끝 (뒤로 안 감)
app.UseRouting();                    // 5. 어느 엔드포인트인지 결정
app.UseCors("game");                 // 6. 라우팅 뒤, 인증 앞
app.UseRateLimiter();                // 7. 인증 뒤가 더 좋을 때도 있다(아래 note)
app.UseAuthentication();             // 8. 토큰을 읽어 User 를 채운다
app.UseAuthorization();              // 9. 그 User 로 권한을 본다
app.MapPlayers().MapShop();          // 10. 끝점

app.Run();

직접 만들어 보면 구조가 보입니다

// 요청 하나에 걸린 시간을 재는 최소 미들웨어
app.Use(async (ctx, next) =>
{
    var sw = Stopwatch.StartNew();
    ctx.Response.OnStarting(() =>          // 헤더는 본문이 나가기 직전까지만 바꿀 수 있다
    {
        ctx.Response.Headers["X-Elapsed-ms"] = sw.ElapsedMilliseconds.ToString();
        return Task.CompletedTask;
    });
    await next(ctx);                       // ★ 여기서 안쪽 전부가 실행된다
    // next() 가 돌아온 뒤 = 응답이 나가는 길 — 이미 본문이 나갔다면
    // 여기서 헤더를 고치면 예외입니다 (그래서 위의 OnStarting)
});

// next() 를 부르지 않으면 거기서 요청이 끝난다 — 이것이 "단락(short-circuit)"
app.Use(async (ctx, next) =>
{
    if (ctx.Request.Headers["X-Client-Ver"] != "1.4.2")
    {
        ctx.Response.StatusCode = 426;     // Upgrade Required
        await ctx.Response.WriteAsJsonAsync(new { need = "1.4.2" });
        return;                            // next 호출 없음 → 뒤로 안 감
    }
    await next(ctx);
});

설정 읽기

// appsettings.json (공통) → appsettings.Production.json (덮어쓰기)
{
  "Game": {
    "MaxPartySize": 4,
    "DailyRewardHourUtc": 0,
    "Shop": { "RefreshMinutes": 60 }
  },
  "ConnectionStrings": { "Db": "Host=...;Database=game" }
}

public sealed class GameOptions
{
    public const string Section = "Game";
    [Range(1, 8)] public int MaxPartySize { get; init; } = 4;
    public int DailyRewardHourUtc { get; init; }
}

builder.Services.AddOptions<GameOptions>()
    .Bind(builder.Configuration.GetSection(GameOptions.Section))
    .ValidateDataAnnotations()
    .ValidateOnStart();            // ★ 잘못된 설정이면 시작 자체를 막는다

// 쓰는 쪽
public class PartyService(IOptions<GameOptions> opt) { ... }

비밀은 설정 파일에 넣지 않는다

# 개발 — 사용자 비밀 저장소 (저장소에 안 올라감)
dotnet user-secrets init
dotnet user-secrets set "ConnectionStrings:Db" "Host=localhost;..."

# 운영 — 환경 변수 (: 는 __ 로)
ConnectionStrings__Db="Host=prod;..."
Game__MaxPartySize=6

환경은 이렇게 갈립니다

# 환경 이름을 정하는 것은 이 변수 하나입니다
ASPNETCORE_ENVIRONMENT=Development   # 기본값
ASPNETCORE_ENVIRONMENT=Staging
ASPNETCORE_ENVIRONMENT=Production

# 컨테이너에서는 보통 이렇게
docker run -e ASPNETCORE_ENVIRONMENT=Production \
           -e ConnectionStrings__Db="Host=db;..." \
           -e Game__MaxPartySize=6  gameapi:1.4.2

// 코드에서 갈라야 할 때 — 최소한으로만
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();                  // 문서는 개발에서만
    app.UseDeveloperExceptionPage();   // 스택 추적 노출 — 절대 운영 금지
}
else
{
    app.UseExceptionHandler("/error"); // 운영은 내용을 감춘다
    app.UseHsts();
}

// 커스텀 환경도 됩니다
if (app.Environment.IsEnvironment("LoadTest")) { /* 결제만 가짜로 */ }

설정을 안전하게 쓰는 세 가지 방법

// ① IOptions — 대부분 이걸로. 시작 시 한 번 바인딩되고 안 바뀝니다
public class PartyService(IOptions<GameOptions> opt)
{
    private readonly GameOptions _o = opt.Value;
}

// ② IOptionsSnapshot — 요청마다 다시 읽습니다 (Scoped 전용)
//    appsettings 를 고치면 재시작 없이 반영됩니다
public class ShopService(IOptionsSnapshot<GameOptions> opt) { ... }

// ③ IOptionsMonitor — 싱글턴에서 변경을 감지할 때
public class RewardScheduler
{
    public RewardScheduler(IOptionsMonitor<GameOptions> m)
        => m.OnChange(o => Reschedule(o.DailyRewardHourUtc));
}

기본

public class GameDb(DbContextOptions<GameDb> o) : DbContext(o)
{
    public DbSet<Player> Players => Set<Player>();
    public DbSet<Item>   Items   => Set<Item>();

    protected override void OnModelCreating(ModelBuilder b)
    {
        b.Entity<Player>(e =>
        {
            e.HasKey(x => x.Id);
            e.HasIndex(x => x.Nickname).IsUnique();
            e.Property(x => x.Nickname).HasMaxLength(20).IsRequired();
            e.HasMany(x => x.Items).WithOne(i => i.Owner)
             .OnDelete(DeleteBehavior.Cascade);
        });
    }
}

builder.Services.AddDbContext<GameDb>(o =>
    o.UseNpgsql(builder.Configuration.GetConnectionString("Db")));

dotnet ef migrations add Init
dotnet ef database update

느려지는 세 가지

var players = await db.Players.ToListAsync();
foreach (var p in players)
    Console.WriteLine(p.Items.Count);
// 지연 로딩을 켰다면 플레이어 수만큼 쿼리가 더 나간다
// (안 켰다면 Items 가 비어 조용히 0 이 찍힌다)

var players = await db.Players
    .Include(p => p.Items)
    .AsNoTracking()          // 읽기 전용이면 필수
    .ToListAsync();

• AsNoTracking — 조회 전용 쿼리에 붙이면 메모리·속도가 크게 개선됩니다
• 필요한 컬럼만 — Select(p => new { p.Id, p.Nickname })
• 페이징 필수 — Skip/Take 없이 전체를 가져오지 마세요
• 인덱스 — 조회 조건에 쓰는 컬럼에는 반드시

토큰 발급과 검증

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(o =>
    {
        o.TokenValidationParameters = new()
        {
            ValidateIssuer = true, ValidIssuer = cfg["Jwt:Issuer"],
            ValidateAudience = true, ValidAudience = cfg["Jwt:Audience"],
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromSeconds(30),      // 기본 5분은 너무 길다
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(cfg["Jwt:Key"]!)),
        };
    });
app.UseAuthentication();
app.UseAuthorization();

string IssueToken(Player p)
{
    var claims = new[]
    {
        new Claim(JwtRegisteredClaimNames.Sub, p.Id.ToString()),
        new Claim("nick", p.Nickname),
        new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
    };
    var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);
    var token = new JwtSecurityToken(issuer, audience, claims,
                    expires: DateTime.UtcNow.AddMinutes(30), signingCredentials: creds);
    return new JwtSecurityTokenHandler().WriteToken(token);
}

게스트 → 계정 연동

// ① 첫 실행 — 기기 식별자로 게스트 계정 생성
app.MapPost("/auth/guest", async (GuestDto d, GameDb db) =>
{
    var p = await db.Players.FirstOrDefaultAsync(x => x.DeviceId == d.DeviceId)
            ?? db.Players.Add(new Player { DeviceId = d.DeviceId }).Entity;
    await db.SaveChangesAsync();
    return Results.Ok(new { token = IssueToken(p), refresh = IssueRefresh(p) });
});

// ② 나중에 소셜 계정 연결 (기기 분실 대비)
app.MapPost("/auth/link", async (LinkDto d, ClaimsPrincipal user, GameDb db) =>
{
    var provider = await VerifyExternalAsync(d.Provider, d.IdToken);   // ★ 서버 검증
    if (provider is null) return Results.Unauthorized();

    var me = await db.Players.FindAsync(user.PlayerId());
    if (await db.Players.AnyAsync(x => x.ExternalId == provider.Id))
        return Results.Conflict("이미 연결된 계정입니다");

    me!.ExternalId = provider.Id;
    await db.SaveChangesAsync();
    return Results.NoContent();
}).RequireAuthorization();

입력 검증

// FluentValidation
public class BuyItemValidator : AbstractValidator<BuyItemDto>
{
    public BuyItemValidator()
    {
        RuleFor(x => x.ItemId).GreaterThan(0);
        RuleFor(x => x.Count).InclusiveBetween(1, 99);
        RuleFor(x => x.Nickname).MaximumLength(20)
            .Matches("^[가-힣a-zA-Z0-9]+$").WithMessage("특수문자는 쓸 수 없습니다");
    }
}

app.MapPost("/shop/buy", async (BuyItemDto d, IValidator<BuyItemDto> v, IShop shop) =>
{
    var r = await v.ValidateAsync(d);
    if (!r.IsValid) return Results.ValidationProblem(r.ToDictionary());

    // ★ 가격은 서버가 조회 — 클라이언트가 보낸 금액은 절대 쓰지 않는다
    return await shop.BuyAsync(d.ItemId, d.Count) switch
    {
        BuyResult.Ok o        => Results.Ok(o),
        BuyResult.NoGold      => Results.BadRequest(new { code = "NO_GOLD" }),
        BuyResult.SoldOut     => Results.Conflict(new { code = "SOLD_OUT" }),
        _                     => Results.Problem(),
    };
});

에러 형식 통일

app.UseExceptionHandler(x => x.Run(async ctx =>
{
    var ex = ctx.Features.Get<IExceptionHandlerFeature>()?.Error;
    var (status, code) = ex switch
    {
        NotFoundException      => (404, "NOT_FOUND"),
        DomainRuleException d  => (400, d.Code),
        _                      => (500, "INTERNAL"),
    };

    log.LogError(ex, "요청 실패 {Path}", ctx.Request.Path);
    ctx.Response.StatusCode = status;
    await ctx.Response.WriteAsJsonAsync(new
    {
        code,
        traceId = Activity.Current?.Id ?? ctx.TraceIdentifier,   // ★ 문의 대응용
    });
}));

허브

[Authorize]
public class LobbyHub : Hub
{
    public override async Task OnConnectedAsync()
    {
        var guildId = Context.User!.FindFirst("guild")?.Value;
        if (guildId is not null)
            await Groups.AddToGroupAsync(Context.ConnectionId, $"guild:{guildId}");
        await base.OnConnectedAsync();
    }

    public async Task SendGuild(string text)
    {
        var gid = Context.User!.FindFirst("guild")!.Value;
        await Clients.Group($"guild:{gid}")
                     .SendAsync("GuildChat", Context.UserIdentifier, text);
    }
}

app.MapHub<LobbyHub>("/hub/lobby");

// 서버 다른 곳에서 밀어 넣기
await hub.Clients.User(playerId.ToString()).SendAsync("MailArrived", mail);

여러 대로 늘릴 때

// 서버가 2대가 되는 순간, 다른 서버에 붙은 사용자에게 못 보냅니다
builder.Services.AddSignalR()
    .AddStackExchangeRedis(cfg.GetConnectionString("Redis")!);   // ← 한 줄

• Sticky 세션이 필요합니다(로드밸런서 설정) — 협상 요청과 연결이 같은 서버로
• 재연결을 클라이언트에 붙이고, 재연결 직후 놓친 것 당겨오기
• Unity 클라이언트는 SignalR .NET 클라이언트를 그대로 씁니다

클라이언트 — 재연결과 놓친 것 당겨오기

// Unity·콘솔 공통 (Microsoft.AspNetCore.SignalR.Client)
var conn = new HubConnectionBuilder()
    .WithUrl("https://api.game.com/hub/lobby", o =>
        o.AccessTokenProvider = () => Task.FromResult(_token)!)
    .WithAutomaticReconnect(new[] {                 // 재시도 간격을 직접
        TimeSpan.Zero, TimeSpan.FromSeconds(2),
        TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(15) })
    .Build();

conn.On<string, string>("GuildChat", (who, text) => Ui.AddChat(who, text));
conn.On<MailDto>("MailArrived", m => Ui.MailBadge(m));

// ★ 재연결 직후가 핵심 — 끊겨 있던 동안의 것을 REST 로 당겨온다
conn.Reconnected += async _ =>
{
    var missed = await _http.GetFromJsonAsync<MailDto[]>(
        $"/mail?since={_lastSeenUtc:o}");
    foreach (var m in missed!) Ui.MailBadge(m);
    _lastSeenUtc = DateTime.UtcNow;
};

conn.Closed += async _ =>                            // 전부 실패하면 수동 재시도
{
    await Task.Delay(TimeSpan.FromSeconds(30));
    await conn.StartAsync();
};

await conn.StartAsync();

서버 — 실전에서 걸리는 것들

builder.Services.AddSignalR(o =>
{
    o.EnableDetailedErrors = builder.Environment.IsDevelopment();
    o.MaximumReceiveMessageSize = 32 * 1024;    // 채팅에 32KB 면 충분
    o.ClientTimeoutInterval = TimeSpan.FromSeconds(30);
    o.KeepAliveInterval     = TimeSpan.FromSeconds(10);
})
.AddStackExchangeRedis(cfg.GetConnectionString("Redis")!,
    o => o.Configuration.ChannelPrefix = RedisChannel.Literal("game"));

// 쿼리스트링 토큰 — 웹소켓은 Authorization 헤더를 못 붙이는 클라가 있습니다
builder.Services.Configure<JwtBearerOptions>(
    JwtBearerDefaults.AuthenticationScheme, o =>
{
    o.Events = new JwtBearerEvents
    {
        OnMessageReceived = ctx =>
        {
            var t = ctx.Request.Query["access_token"];
            if (!string.IsNullOrEmpty(t) &&
                ctx.HttpContext.Request.Path.StartsWithSegments("/hub"))
                ctx.Token = t;
            return Task.CompletedTask;
        }
    };
});

// 허브에서 무거운 일을 하지 마세요 — 큐에 넣고 바로 반환
public async Task SendGuild(string text)
{
    if (text.Length > 200) throw new HubException("너무 깁니다");
    if (!_rate.TryAcquire(Context.UserIdentifier!))   // 도배 방지
        throw new HubException("잠시 후 다시");

    await _chatQueue.EnqueueAsync(new ChatMsg(Context.UserIdentifier!, text));
}

• 연결 수 = 메모리입니다 — 대략 연결 하나에 수십 KB. 10만 연결이면 인스턴스를 나눠야 합니다
• HubException 만 클라에 문구가 전달됩니다. 다른 예외는 "An unexpected error" 로 감춰집니다
• OnDisconnectedAsync 는 안 불릴 수 있습니다 — 프로세스가 죽으면 그냥 사라집니다. 접속 상태를 DB 에 쓰려면 TTL 있는 Redis 키로

캐시

// 하이브리드 캐시 (.NET 9+) — 메모리 + 분산을 한 API 로
builder.Services.AddHybridCache();

public async Task<ShopData> GetShopAsync(CancellationToken ct) =>
    await cache.GetOrCreateAsync(
        "shop:daily",
        async token => await db.LoadShopAsync(token),
        new HybridCacheEntryOptions
        {
            Expiration = TimeSpan.FromMinutes(10),
            LocalCacheExpiration = TimeSpan.FromMinutes(1),
        }, cancellationToken: ct);

// 무효화
await cache.RemoveAsync("shop:daily", ct);

백그라운드 작업

public class DailyResetService(IServiceScopeFactory scopes, ILogger<DailyResetService> log)
    : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            var next = NextUtcMidnight();
            await Task.Delay(next - DateTimeOffset.UtcNow, ct);

            using var scope = scopes.CreateScope();          // ★ Scoped 를 쓰려면 필수
            var db = scope.ServiceProvider.GetRequiredService<GameDb>();
            try { await ResetDailyAsync(db, ct); }
            catch (Exception e) { log.LogError(e, "일일 초기화 실패"); }
        }
    }
}
builder.Services.AddHostedService<DailyResetService>();

구매 — 한 트랜잭션으로

public async Task<BuyResult> BuyAsync(int playerId, int itemId, int count,
                                       string idempotencyKey, CancellationToken ct)
{
    // ① 같은 요청이 두 번 오면 이전 결과를 그대로 (네트워크 재시도 대비)
    if (await _db.Receipts.FindAsync([idempotencyKey], ct) is {} done)
        return done.Result;

    await using var tx = await _db.Database.BeginTransactionAsync(ct);

    // ② 가격은 서버가 조회 — 클라이언트 값은 쓰지 않는다
    var item = await _db.ItemDefs.FindAsync([itemId], ct)
               ?? throw new NotFoundException();
    var cost = item.Price * count;

    // ③ 재화 차감은 조건부 UPDATE 로 (동시 요청에도 음수가 되지 않게)
    var affected = await _db.Players
        .Where(p => p.Id == playerId && p.Gold >= cost)
        .ExecuteUpdateAsync(s => s.SetProperty(p => p.Gold, p => p.Gold - cost), ct);
    if (affected == 0) return BuyResult.NoGold;

    // ④ 지급 · 영수증 · 로그를 같은 트랜잭션에
    _db.Inventories.Add(new Inventory { PlayerId = playerId, ItemId = itemId, Count = count });
    _db.Receipts.Add(new Receipt { Key = idempotencyKey, Result = BuyResult.Ok });
    _db.GoldLogs.Add(new GoldLog { PlayerId = playerId, Delta = -cost, Reason = "buy" });

    await _db.SaveChangesAsync(ct);
    await tx.CommitAsync(ct);
    return BuyResult.Ok;
}

지켜야 할 원칙

• 재화 변동은 반드시 로그 — 문의·환불·치트 조사의 유일한 근거입니다
• 조건부 UPDATE — WHERE gold >= cost 로 DB 가 판정하게
• 멱등 키 — 같은 요청이 두 번 와도 한 번만 처리
• 지급과 차감은 같은 트랜잭션 — 중간에 죽으면 둘 다 취소
• 수량 상한 — 인벤토리·우편함 한도를 서버가 강제
• 시간은 서버 기준 — 클라이언트 시각으로 일일 보상을 주면 조작됩니다

구조적 로깅

// 문자열을 조립하지 말고 값을 넘기세요 (검색·집계가 됩니다)
log.LogInformation("아이템 구매 {PlayerId} {ItemId} {Cost}", pid, iid, cost);   // ✓
log.LogInformation($"아이템 구매 {pid}");                                      // ✗

// 요청 전체에 공통 값 붙이기
using (log.BeginScope(new Dictionary<string, object>
       { ["PlayerId"] = pid, ["TraceId"] = Activity.Current?.Id! }))
{
    await HandleAsync();          // 이 안의 모든 로그에 자동으로 붙습니다
}

// OpenTelemetry — 지표·추적을 표준 형식으로
builder.Services.AddOpenTelemetry()
    .WithMetrics(m => m.AddAspNetCoreInstrumentation()
                       .AddRuntimeInstrumentation()
                       .AddPrometheusExporter())
    .WithTracing(t => t.AddAspNetCoreInstrumentation()
                       .AddEntityFrameworkCoreInstrumentation()
                       .AddOtlpExporter());
app.MapPrometheusScrapingEndpoint();

무엇을 남길 것인가

• 남겨야 — 재화 변동 · 아이템 획득/소모 · 결제 · 로그인 · 밴
• 남기지 말아야 — 비밀번호 · 토큰 · 주민번호 · 카드번호
• 레벨 기준 — Error 는 사람이 조치해야 하는 것만. 나머지는 Warning 이하로
• 보관 기간 — 재화 로그는 길게(분쟁), 일반 로그는 짧게(비용)

단위 테스트

public class DamageTests
{
    [Theory]
    [InlineData(100, 20, 0.0, 80)]
    [InlineData(100, 20, 0.5, 90)]     // 방어율 50%
    [InlineData(100, 999, 0.0, 0)]     // 체력은 0 미만이 되지 않는다
    public void 데미지_계산(int hp, int atk, double def, int expected)
    {
        var result = Combat.Apply(hp, atk, def);
        Assert.Equal(expected, result);
    }
}

통합 테스트 — 진짜 DB 로

public class ApiFixture : WebApplicationFactory<Program>, IAsyncLifetime
{
    private readonly PostgreSqlContainer _db =
        new PostgreSqlBuilder().WithImage("postgres:17-alpine").Build();

    public async Task InitializeAsync() => await _db.StartAsync();
    async Task IAsyncLifetime.DisposeAsync() => await _db.DisposeAsync();   // (xUnit v2 기준)

    protected override void ConfigureWebHost(IWebHostBuilder b) =>
        b.UseSetting("ConnectionStrings:Db", _db.GetConnectionString());
}

public class ShopTests(ApiFixture f) : IClassFixture<ApiFixture>
{
    [Fact]
    public async Task 골드가_부족하면_구매_실패()
    {
        var client = f.CreateClient();
        var res = await client.PostAsJsonAsync("/shop/buy", new { itemId = 1, count = 99 });
        Assert.Equal(HttpStatusCode.BadRequest, res.StatusCode);
    }
}

동시 요청 — 실제 사고를 재현하는 테스트

[Fact]
public async Task 한정_아이템은_재고만큼만_팔린다()
{
    await Seed.ItemAsync(id: 77, stock: 10);

    // 100명이 동시에 산다
    var clients = Enumerable.Range(0, 100)
        .Select(i => f.CreateAuthedClient(playerId: 1000 + i));

    var results = await Task.WhenAll(clients.Select(c =>
        c.PostAsJsonAsync("/shop/buy", new { itemId = 77, count = 1 })));

    var ok = results.Count(r => r.IsSuccessStatusCode);
    Assert.Equal(10, ok);                                   // ★ 정확히 10명
    Assert.Equal(0, await Db.StockOfAsync(77));             // 마이너스 금지
    Assert.Equal(10, await Db.PurchaseLogCountAsync(77));   // 로그도 정확히
}

[Fact]
public async Task 같은_요청을_두_번_보내도_한_번만_처리된다()
{
    var key = Guid.NewGuid().ToString();
    var body = new { itemId = 1, count = 1 };

    var c = f.CreateAuthedClient(playerId: 7);
    c.DefaultRequestHeaders.Add("Idempotency-Key", key);

    var r1 = await c.PostAsJsonAsync("/shop/buy", body);
    var r2 = await c.PostAsJsonAsync("/shop/buy", body);   // 재전송

    Assert.True(r1.IsSuccessStatusCode && r2.IsSuccessStatusCode);
    Assert.Equal(await r1.Content.ReadAsStringAsync(),
                 await r2.Content.ReadAsStringAsync());     // 같은 결과
    Assert.Equal(1, await Db.PurchaseLogCountAsync(1));     // 차감은 한 번
}

외부 의존은 가짜로 — 그러나 DB 는 진짜로

public class ApiFixture : WebApplicationFactory<Program>
{
    protected override void ConfigureWebHost(IWebHostBuilder b) =>
        b.ConfigureTestServices(s =>
        {
            // 결제·푸시만 가짜로 바꾼다
            s.RemoveAll<IStoreVerifier>();
            s.AddSingleton<IStoreVerifier, AlwaysValidVerifier>();
            s.RemoveAll<IPushSender>();
            s.AddSingleton<IPushSender, RecordingPushSender>();

            // 시간도 고정 — "매일 0시 보상" 같은 것을 테스트하려면 필수
            s.AddSingleton<TimeProvider>(
                new FakeTimeProvider(new DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc)));
        });
}

// 확률은 시드를 고정해서 검증합니다
[Fact]
public void 뽑기_확률이_표와_맞는다()
{
    var rng = new Random(42);
    var box = new GachaBox(rng);
    var counts = Enumerable.Range(0, 100_000)
        .Select(_ => box.Draw().Grade)
        .GroupBy(g => g).ToDictionary(g => g.Key, g => g.Count());

    Assert.InRange(counts["SSR"] / 100_000.0, 0.028, 0.032);   // 표기 3%
}

• TimeProvider(.NET 8+)를 쓰면 DateTime.UtcNow 를 테스트에서 갈아 끼울 수 있습니다 — 일일 보상·쿨타임·이벤트 기간 테스트가 가능해집니다
• 확률 표기는 법적 고지 대상인 나라가 많습니다. 표와 코드가 어긋나지 않는지 테스트로 묶어 두세요
• 테스트마다 DB 를 트랜잭션으로 감싸 롤백하거나 Respawn 으로 비웁니다 — 순서 의존은 반드시 언젠가 깨집니다
• dotnet test --collect:"XPlat Code Coverage" 로 커버리지를 봅니다. 숫자를 목표로 삼지 말고, 재화·결제 경로가 비어 있는지만 확인하세요

Dockerfile

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY *.sln .
COPY src/GameApi/*.csproj src/GameApi/
# ★ 의존성 레이어를 먼저 (캐시) — 복사한 프로젝트만 복원
RUN dotnet restore src/GameApi/GameApi.csproj
COPY . .
RUN dotnet publish src/GameApi -c Release -o /app --no-restore

FROM mcr.microsoft.com/dotnet/aspnet:10.0
WORKDIR /app
COPY --from=build /app .
ENV ASPNETCORE_URLS=http://+:8080
EXPOSE 8080
# 루트로 돌리지 않는다 (Dockerfile 은 줄 끝 주석이 안 됩니다)
USER $APP_UID
ENTRYPOINT ["dotnet", "GameApi.dll"]

// 헬스체크 — 로드밸런서가 이걸 보고 트래픽을 넣습니다
builder.Services.AddHealthChecks()
    .AddDbContextCheck<GameDb>()
    .AddRedis(cfg.GetConnectionString("Redis")!);

app.MapHealthChecks("/health/live",     // 살아 있나 (프로세스만 — 검사 0개)
    new() { Predicate = _ => false });
app.MapHealthChecks("/health/ready");   // 받을 준비가 됐나 (DB·캐시 포함)

무중단의 조건

• 그레이스풀 셧다운 — 종료 신호를 받으면 진행 중 요청을 마치고 종료
• readiness 와 liveness 분리 — 준비 안 됐는데 트래픽이 오면 에러가 납니다
• DB 마이그레이션은 하위 호환으로 — 컬럼 삭제는 다음 배포에서
• 무상태 — 세션을 메모리에 두면 확장할 수 없습니다
• 롤백 절차를 미리 문서로

builder.Services.Configure<HostOptions>(o =>
    o.ShutdownTimeout = TimeSpan.FromSeconds(30));   // 마무리 시간 확보