Version 1.34.2 | Production Ready | Unreal Engine 5.5+
This page covers all bucket operations available in the Supabase UE5 Plugin for managing storage buckets and file operations. Bucket operations provide comprehensive file storage management with thread-safe operations, progress tracking, and production-ready error handling.
The Supabase UE5 Plugin provides a complete set of bucket operations for managing files and storage in your Supabase project. All operations are async, thread-safe, and include comprehensive validation and error handling.
Key Features:
Creates a new storage bucket in your Supabase project.
Blueprint Node: Create Bucket Async
C++ Usage:
UAsyncCreateBucket* CreateTask = UAsyncCreateBucket::CreateBucketAsync(
this,
Connection,
TEXT("my-bucket")
);
CreateTask->OnSuccess.AddDynamic(this, &AMyClass::OnBucketCreated);
CreateTask->OnFailure.AddDynamic(this, &AMyClass::OnBucketCreateFailed);
Parameters:
WorldContextObject - World context for the operationConnection - USupabaseConnection instanceBucketName - Name of the bucket to createBucket Naming Rules:
Checks if a bucket exists in your Supabase project.
Blueprint Node: Bucket Exist Async
C++ Usage:
UAsyncBucketExist* ExistTask = UAsyncBucketExist::BucketExistAsync(
this,
Connection,
TEXT("my-bucket")
);
ExistTask->OnSuccess.AddDynamic(this, &AMyClass::OnBucketExists);
ExistTask->OnFailure.AddDynamic(this, &AMyClass::OnBucketCheckFailed);
Parameters:
WorldContextObject - World context for the operationConnection - USupabaseConnection instanceBucketName - Name of the bucket to checkUploads a file to a storage bucket with progress tracking and chunked upload support.
Blueprint Node: Upload File Async
Basic C++ Usage:
UAsyncUploadFile* UploadTask = UAsyncUploadFile::UploadFileAsync(
this,
Connection,
TEXT("avatars"), // Bucket name
TEXT("user123/profile.jpg"), // Remote file path
TEXT("C:/Users/Player/avatar.jpg"), // Local file path
EAuthenticationToken::User
);
UploadTask->OnSuccess.AddDynamic(this, &AMyClass::OnUploadSuccess);
UploadTask->OnFailure.AddDynamic(this, &AMyClass::OnUploadFailed);
Advanced Upload with Progress:
UAsyncUploadFile* UploadTask = UAsyncUploadFile::UploadFileWithProgressAsync(
this,
TEXT("documents"),
TEXT("files/document.pdf"),
TEXT("C:/Documents/file.pdf")
);
// Bind progress tracking
UploadTask->OnProgress.AddDynamic(this, &AMyClass::OnUploadProgress);
// Upload control methods
UploadTask->PauseUpload(); // Pause upload
UploadTask->ResumeUpload(); // Resume upload
UploadTask->CancelUpload(); // Cancel upload
// Get upload status
float Progress = UploadTask->GetUploadProgress(); // 0.0 - 1.0
bool IsUploading = UploadTask->IsUploadInProgress();
Upload Options:
FUploadOptions Options;
Options.UploadMode = EUploadMode::Upsert;
Options.bUseChunkedUpload = true;
Options.ChunkSize = 5 * 1024 * 1024; // 5MB chunks
Options.MaxFileSize = 100 * 1024 * 1024; // 100MB max
Options.Metadata.Add(TEXT("uploaded_by"), TEXT("player123"));
Options.AllowedExtensions.Add(TEXT("jpg"));
Options.AllowedExtensions.Add(TEXT("png"));
UAsyncUploadFile* AdvancedTask = UAsyncUploadFile::UploadFileWithOptionsAsync(
this, BucketName, FilePath, LocalPath, Options
);
File Validation:
< > : " | ? *../ sequences)Downloads a file from a storage bucket with progress tracking.
Blueprint Node: Download File Async
Basic C++ Usage:
UAsyncDownloadFile* DownloadTask = UAsyncDownloadFile::DownloadFileAsync(
this,
TEXT("avatars"), // Bucket name
TEXT("user123/profile.jpg"), // Remote file path
TEXT("C:/Downloads/avatar.jpg") // Local save path
);
DownloadTask->OnSuccess.AddDynamic(this, &AMyClass::OnDownloadSuccess);
DownloadTask->OnFailure.AddDynamic(this, &AMyClass::OnDownloadFailed);
Download with Progress Tracking:
UAsyncDownloadFile* DownloadTask = UAsyncDownloadFile::DownloadFileWithProgressAsync(
this,
BucketName,
FilePath,
LocalSavePath,
true // Enable progress tracking
);
// Bind progress events
DownloadTask->OnProgress.AddDynamic(this, &AMyClass::OnDownloadProgress);
UFUNCTION()
void OnDownloadProgress(float Progress, int32 BytesDownloaded)
{
UE_LOG(LogTemp, Log, TEXT("Download progress: %.2f%% (%d bytes)"),
Progress * 100.0f, BytesDownloaded);
}
Download Features:
Checks if a file exists in a storage bucket.
Blueprint Node: Bucket File Exist Async
C++ Usage:
UAsyncBucketFileExist* FileExistTask = UAsyncBucketFileExist::BucketFileExistAsync(
this,
Connection,
TEXT("avatars"), // Bucket name
TEXT("user123/profile.jpg") // File path
);
FileExistTask->OnSuccess.AddDynamic(this, &AMyClass::OnFileExists);
FileExistTask->OnFailure.AddDynamic(this, &AMyClass::OnFileCheckFailed);
Parameters:
WorldContextObject - World context for the operationConnection - USupabaseConnection instanceBucketName - Name of the bucketFilePath - Path to the file in the bucketAll file operations support different authentication modes:
enum class EAuthenticationToken : uint8
{
User, // User authentication token
Anonymous, // Anonymous key
Service // Service role key
};
Usage Example:
// Upload with user authentication
UAsyncUploadFile* UploadTask = UAsyncUploadFile::UploadFileAsync(
this, Connection, BucketName, FilePath, LocalPath,
EAuthenticationToken::User
);
// Download with service key (higher permissions)
UAsyncDownloadFile* DownloadTask = UAsyncDownloadFile::DownloadFileAsync(
this, Connection, BucketName, FilePath, LocalPath,
EAuthenticationToken::Service
);
Both upload and download operations support comprehensive progress tracking:
Progress Delegate:
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FFileProgressDelegate,
float, Progress, // 0.0 to 1.0
int32, BytesProcessed // Total bytes processed
);
Usage:
UFUNCTION()
void OnFileProgress(float Progress, int32 BytesProcessed)
{
// Update UI progress bar
ProgressBar->SetPercent(Progress);
// Display bytes processed
FString ProgressText = FString::Printf(TEXT("%.1f%% (%s)"),
Progress * 100.0f,
*FormatBytesAsString(BytesProcessed)
);
ProgressLabel->SetText(FText::FromString(ProgressText));
}
All bucket operations include comprehensive error handling with specific error messages:
Common Error Codes:
400 - Bad Request (invalid parameters)401 - Unauthorized (authentication required)403 - Forbidden (insufficient permissions)404 - Not Found (bucket or file doesn’t exist)413 - Payload Too Large (file size exceeds limits)422 - Unprocessable Entity (validation errors)429 - Too Many Requests (rate limit exceeded)500+ - Server ErrorsError Handling Example:
UFUNCTION()
void OnUploadFailed(const FString& ErrorMessage)
{
UE_LOG(LogTemp, Error, TEXT("Upload failed: %s"), *ErrorMessage);
// Handle specific error cases
if (ErrorMessage.Contains(TEXT("413")))
{
// File too large - inform user
ShowMessage(TEXT("File is too large for upload"));
}
else if (ErrorMessage.Contains(TEXT("401")))
{
// Authentication issue - redirect to login
RedirectToLogin();
}
else
{
// Generic error handling
ShowMessage(FString::Printf(TEXT("Upload failed: %s"), *ErrorMessage));
}
}
void AMyActor::BeginDestroy()
{
// Cancel any active uploads/downloads
if (ActiveUploadTask)
{
ActiveUploadTask->CancelUpload();
ActiveUploadTask = nullptr;
}
Super::BeginDestroy();
}
// Good file organization
FString FilePath = FString::Printf(TEXT("users/%s/avatars/%s.jpg"),
*UserID, *FGuid::NewGuid().ToString());
// Avatar: users/123e4567/avatars/uuid.jpg
// Documents: users/123e4567/documents/report.pdf
// Temp files: temp/session_456/upload.tmp
// Optimal upload settings for large files
FUploadOptions Options;
Options.bUseChunkedUpload = true;
Options.ChunkSize = 5 * 1024 * 1024; // 5MB chunks
Options.MaxConcurrentChunks = 3; // Limit concurrent requests
Options.bCompressFile = true; // Enable compression
// Secure upload validation
FUploadOptions SecureOptions;
SecureOptions.AllowedExtensions = {TEXT("jpg"), TEXT("png"), TEXT("gif")};
SecureOptions.MaxFileSize = 10 * 1024 * 1024; // 10MB limit
SecureOptions.bValidateMimeType = true;
SecureOptions.bScanForMalware = true;
void APlayerController::UploadPlayerAvatar(const FString& LocalImagePath)
{
FString RemotePath = FString::Printf(TEXT("avatars/%s/profile.jpg"),
*GetPlayerState()->GetUniqueId().ToString());
UAsyncUploadFile* UploadTask = UAsyncUploadFile::UploadFileAsync(
this,
GetSupabaseConnection(),
TEXT("player-avatars"),
RemotePath,
LocalImagePath,
EAuthenticationToken::User
);
UploadTask->OnSuccess.AddDynamic(this, &APlayerController::OnAvatarUploaded);
UploadTask->OnFailure.AddDynamic(this, &APlayerController::OnAvatarUploadFailed);
UploadTask->OnProgress.AddDynamic(this, &APlayerController::OnAvatarUploadProgress);
}
void AGameMode::DownloadGameAssets(const TArray<FString>& AssetPaths)
{
for (const FString& AssetPath : AssetPaths)
{
FString LocalPath = FPaths::ProjectContentDir() / TEXT("Downloaded") / AssetPath;
UAsyncDownloadFile* DownloadTask = UAsyncDownloadFile::DownloadFileAsync(
this,
TEXT("game-assets"),
AssetPath,
LocalPath
);
DownloadTask->OnSuccess.AddDynamic(this, &AGameMode::OnAssetDownloaded);
DownloadTask->OnFailure.AddDynamic(this, &AGameMode::OnAssetDownloadFailed);
ActiveDownloads.Add(DownloadTask);
}
}
UAsyncCreateBucket - Bucket creation operationsUAsyncBucketExist - Bucket existence checkingUAsyncUploadFile - File upload operations with progressUAsyncDownloadFile - File download operations with progressUAsyncBucketFileExist - File existence checkingEAuthenticationToken - Authentication modes for operationsEUploadMode - Upload behavior (Insert, Upsert, etc.)FSupabaseBooleanDelegate - Success callbacksFSupabaseErrorEvent - Error callbacksFFileProgressDelegate - Progress tracking callbacks