Skip to content

README.md

Latest commit

 

History

History
299 lines (226 loc) · 9.01 KB

README.md

File metadata and controls

299 lines (226 loc) · 9.01 KB
Raw
Game Frame X Logo

GameFrameX Web

License Version Unity Version Documentation

All-in-One Solution for Indie Game Development · Empowering Indie Developers' Dreams


Documentation · Quick Start · QQ Group: 467608841 / 233840761


English | 简体中文 | 繁體中文 | 日本語 | 한국어

Project Overview

GameFrameX Web is a high-performance Unity HTTP networking library that provides a clean and easy-to-use API for handling various network request scenarios. It supports GET and POST requests, and can process strings, JSON, binary data, and other formats.

Features

  • High-Performance Async - Based on C# Task async pattern, supports async/await
  • Multiple Data Formats - String, JSON, binary data, Protocol Buffers
  • Cross-Platform - Supports WebGL, PC, and mobile platforms
  • Connection Pool Management - Smart connection reuse with max concurrent connections control
  • Secure & Reliable - Comprehensive error handling and timeout mechanisms
  • Easy to Extend - Modular design, supports custom data serialization

Quick Start

Installation

Choose one of the following methods:

  1. Edit your Unity project's Packages/manifest.json and add the scopedRegistries section:

    {
  "scopedRegistries": [
    {
      "name": "GameFrameX",
      "url": "https://gameframex.upm.alianblank.uk",
      "scopes": [
        "com.gameframex"
      ]
    }
  ],
  "dependencies": {
    "com.gameframex.unity.web": "1.3.5"
  }
}

    scopes controls which packages are resolved through this registry. Only packages whose names start with com.gameframex will be fetched from it.

  2. Add to manifest.json dependencies:

    {
   "com.gameframex.unity.web": "https://github.com/gameframex/com.gameframex.unity.web.git"
}

  3. Use Package Manager in Unity with Git URL: https://github.com/gameframex/com.gameframex.unity.web.git

  4. Clone the repository into your Unity project's Packages directory. It will be loaded automatically.

Usage Examples

Binary Data Upload

public async Task UploadBinaryDataAsync(byte[] fileData, string fileName)
{
    var webManager = GameFrameworkEntry.GetModule<IWebManager>();

    var queryParams = new Dictionary<string, string>
    {
        { "fileName", fileName }
    };

    var headers = new Dictionary<string, string>
    {
        { "Content-Type", "application/octet-stream" },
        { "Authorization", "Bearer your-token" }
    };

    WebBufferResult result = await webManager.PostToBytes(
        "https://api.example.com/upload",
        fileData,
        queryParams,
        headers
    );

    if (result.IsSuccess)
    {
        Debug.Log("Upload successful!");
        byte[] responseData = result.Data;
    }
}

Using Protocol Buffers

[ProtoContract]
public class UserRequest
{
    [ProtoMember(1)]
    public string UserId { get; set; }
}

[ProtoContract]
public class UserResponse
{
    [ProtoMember(1)]
    public string UserName { get; set; }

    [ProtoMember(2)]
    public string Email { get; set; }
}

public async Task<UserResponse> GetUserProtoBufAsync(string userId)
{
    var request = new UserRequest { UserId = userId };
    return await webManager.PostProtoBuf<UserResponse>(
        "https://api.example.com/user/protobuf",
        request
    );
}

Error Handling

public async Task<string> SafeWebRequestAsync(string url)
{
    try
    {
        return await webManager.GetToString(url);
    }
    catch (WebException ex) when (ex.Status == WebExceptionStatus.Timeout)
    {
        Debug.LogError("Request timeout: " + ex.Message);
        return null;
    }
    catch (IOException ex)
    {
        Debug.LogError("Network IO error: " + ex.Message);
        return null;
    }
    catch (Exception ex)
    {
        Debug.LogError("Request failed: " + ex.Message);
        return null;
    }
}

API Reference

Core Interface: IWebManager

GET Requests

Task<string> GetToString(string url);
Task<string> GetToString(string url, Dictionary<string, string> queryString);
Task<string> GetToString(string url, Dictionary<string, string> queryString, Dictionary<string, string> header);

Task<byte[]> GetToBytes(string url);
Task<byte[]> GetToBytes(string url, Dictionary<string, string> queryString);
Task<byte[]> GetToBytes(string url, Dictionary<string, string> queryString, Dictionary<string, string> header);

POST Requests

Task<string> PostToString(string url, Dictionary<string, string> formData = null);
Task<string> PostToString(string url, Dictionary<string, string> formData, Dictionary<string, string> queryString);
Task<string> PostToString(string url, Dictionary<string, string> formData, Dictionary<string, string> queryString, Dictionary<string, string> header);

Task<byte[]> PostToBytes(string url, Dictionary<string, string> formData);
Task<byte[]> PostToBytes(string url, Dictionary<string, string> formData, Dictionary<string, string> queryString);
Task<byte[]> PostToBytes(string url, Dictionary<string, string> formData, Dictionary<string, string> queryString, Dictionary<string, string> header);

Task<WebBufferResult> PostToBytes(string url, byte[] binaryData, Dictionary<string, string> queryString, Dictionary<string, string> header, object userData = null);

Advanced Features

// Protocol Buffers support
Task<T> GetProtoBuf<T>(string url) where T : class, IExtensible;
Task<T> PostProtoBuf<T>(string url, IExtensible requestData) where T : class, IExtensible;

// JSON support (via extension methods)
Task<T> GetJson<T>(string url);
Task<T> PostJson<T>(string url, object data);

Configuration Options

// Request timeout (default: 30 seconds)
TimeSpan RequestTimeout { get; set; }

// Max concurrent connections (default: 8)
int MaxConnectionPerServer { get; set; }

// Enable/disable verbose logging
bool EnableWebLog { get; set; }

Platform Support

Platform Supported Notes
Windows Yes Full support
macOS Yes Full support
Linux Yes Full support
Android Yes Full support
iOS Yes Full support
WebGL Yes Single-threaded, all requests processed on main thread

Configuration

private void ConfigureWebManager()
{
    var webManager = GameFrameworkEntry.GetModule<IWebManager>();

    // Set request timeout to 60 seconds
    webManager.RequestTimeout = TimeSpan.FromSeconds(60);

    // Set max concurrent connections to 16
    webManager.MaxConnectionPerServer = 16;

    // Enable verbose logging
    webManager.EnableWebLog = true;
}

Troubleshooting

  1. WebGL Platform Limitations

    • WebGL does not support multi-threading; all requests are processed on the main thread
    • Use await for async operations instead of blocking calls

  2. CORS Issues

    • Ensure the server has correct CORS headers configured
    • For WebGL builds, the server must support OPTIONS preflight requests

  3. HTTPS Certificate Issues

    • Mobile devices may require custom certificate validation
    • Use a custom certificate validation callback

Documentation & Resources

Community & Support

If you have any questions or need help, reach out through:

Contributing

Contributions are welcome! Please feel free to submit Issues and Pull Requests.

  1. Fork this project
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Create a Pull Request

Changelog

See CHANGELOG.md for detailed version history.

Dependencies

Package Description
com.gameframex.unity 1.1.1
com.gameframex.unity.network 2.5.1

License

See LICENSE.md for license information.