🇬🇧 English | 🇺🇦 Українська

1. Швидкий старт¶

Мета розділу — за десять хвилин завантажити файл у сховище й зчитати його назад, не написавши жодного рядка C++.

Встановлення¶

Скопіюйте теку S3CompatibleStorageDemo/ у каталог Plugins/ вашого проєкту.
Перегенеруйте файли проєкту та зберіть його.
Переконайтеся, що плагін увімкнено: Edit → Plugins → Networking → S3 Compatible Storage.

Крок 1. Підключення¶

Project Settings → Plugins → S3 Compatible Storage

Почніть із поля Provider. Воно найважливіше: обравши провайдера, ви одразу отримуєте правильний стиль адресації, а для деяких сервісів — і готову адресу. Саме тут зазвичай ховається причина того, що «нічого не працює, хоча ключі правильні».

Провайдер	Endpoint URL	Region
Amazon S3	лишіть порожнім	регіон вашого бакета
Cloudflare R2	`https://<account-id>.r2.cloudflarestorage.com`	`auto`
Backblaze B2	`https://s3.<region>.backblazeb2.com`	з консолі B2
Google Cloud Storage	лишіть порожнім	`auto`
MinIO	`http://host:9000`	будь-який, але він бере участь у підписі
Wasabi, DigitalOcean Spaces	залежить від регіону	залежить від регіону

Заповніть Default Bucket — з ним працюватимуть кнопки перевірки й підсистема.

Amazon S3: не вписуйте регіональну адресу вручну. Лишіть Endpoint URL порожнім і просто вкажіть регіон. Плагін сам звернеться до s3.<region>.amazonaws.com, бо s3.amazonaws.com обслуговує лише us-east-1.

Крок 2. Ключі¶

Прокрутіть до секції S3 Credentials (Editor Only) й впишіть Access Key ID та Secret Access Key.

Ця секція навмисно окрема від решти налаштувань. Вона зберігається у вашому особистому EditorPerProjectUserSettings.ini, який лежить у теці Saved/, виключений зі системи контролю версій стандартним .gitignore і ніколи не потрапляє в зібрану гру. На головній сторінці налаштувань поля для ключів немає взагалі — і це теж навмисно: усе, що там збережеться, поїхало б у DefaultGame.ini всередині збірки.

Для зібраної гри ключі беруться зовсім з іншого місця — див. Облікові дані.

Крок 3. Перевірка¶

Угорі сторінки налаштувань є чотири кнопки:

Кнопка	Що робить
Test Connection	Один справжній запит: чи доступна адреса, чи збігається підпис, чи читається бакет
List Objects	Показує вміст бакета
Run Round Trip Check	Завантажує пробний об'єкт, зчитує його, звіряє байти й видаляє. Потребує права на запис
Clear Report	Очищає звіт

Результат з'являється у полі Report одразу під кнопками. Якщо перевірка не пройшла, у звіті буде не лише текст помилки від провайдера, а й рядок із порадою, що змінити.

Кнопки працюють тим самим кодом, що й зібрана гра, тому зелений результат тут означає, що конфігурація справді робоча, а не просто синтаксично правильна.

Крок 4. Завантаження файлу з Blueprint¶

Event BeginPlay
   │
   ├─► Get S3 Subsystem
   │        │
   │        └─► Get Default S3 Client ──┐
   │                                     │
   └─────────────────────────────────────┴─► S3 Upload File
                                                  Bucket Name : my-bucket
                                                  Object Key  : saves/player.sav
                                                  Local File Path : Saved/SaveGames/player.sav
                                                  │
                                                  ├─ On Started  → зберегти Transfer у змінну
                                                  ├─ On Progress → оновити ProgressBar
                                                  ├─ On Success  → Print String "Готово"
                                                  └─ On Failure  → Print String (Get S3 Diagnostic Hint)

Get S3 Subsystem — це стандартна нода Unreal: Get Game Instance Subsystem із класом S3 Subsystem. Підсистема створює клієнта з ваших налаштувань, тримає його живим і віддає той самий екземпляр за кожним викликом.

Про Local File Path. Значення вище — відносний шлях: плагін сам розгортає його відносно кореня проєкту (Saved/SaveGames/player.sav стає, наприклад, C:/MyProject/Saved/SaveGames/player.sav), однаково і в редакторі, і в зібраній грі. Так само підійде повний абсолютний шлях на кшталт C:/Users/You/Desktop/player.sav. Не підійде шлях ассета на кшталт /Game/... — це посилання на об'єкт у Content Browser, а не на файл на диску. Повний розбір усіх варіантів, з прикладами під кожну платформу — у розділі «Шлях до файлу: абсолютний чи відносний».

Що робити з пінами¶

On Started спрацьовує одразу, ще до передавання даних. Дає об'єкт Transfer — збережіть його у змінну, якщо хочете дати гравцеві кнопку «Скасувати» або малювати прогрес.
On Progress спрацьовує в міру руху байтів. У структурі є Percentage для смужки прогресу і bTotalKnown — поки він false, загальний розмір ще невідомий, тож показуйте невизначений індикатор.
On Success і On Failure — рівно один із двох, завжди. Тому очищення можна писати в одному місці.

Усі піни спрацьовують в ігровому потоці, тож із них можна безпечно чіпати актори й віджети.

Крок 5. Зчитування назад¶

S3 Download File
   Bucket Name     : my-bucket
   Object Key      : saves/player.sav
   Local File Path : Saved/SaveGames/player-downloaded.sav
   │
   ├─ On Success → файл уже на диску
   └─ On Failure → показати Get S3 Diagnostic Hint

Файл пишеться на диск у міру надходження, тому пам'ять не залежить від його розміру. Пін Data на успіху порожній — байти у файлі. Якщо зчитування не вдалося, недописаний файл видаляється: half-файл, який виглядає як успішно завантажений, гірший за його відсутність.

Щоб отримати дані в пам'ять — наприклад, для невеликого JSON — беріть S3 Download Bytes.

Типові перешкоди на старті¶

Симптом	Причина
`SignatureDoesNotMatch` на не-Amazon сервісі	Вимкнено Path Style Addressing. Оберіть провайдера зі списку — і воно ввімкнеться саме
`NoSuchBucket` на MinIO	MinIO не створює бакети автоматично. Скористайтеся нодою S3 Create Bucket або консоллю MinIO
Нода нічого не робить, у пінах тиша	У піні Client порожньо. Візьміть клієнта з підсистеми
403 на всьому підряд у зібраній грі	У збірці немає ключів — вони лишилися в редакторських налаштуваннях. Див. Облікові дані
`Cannot read <шлях>` на `S3 Upload File`	Файла немає саме там, куди веде шлях. Для відносного шляху це `Saved/...` у корені проєкту, а не там, де відкрито провідник ОС — див. «Шлях до файлу»

Далі: 2. Налаштування