kongregate / kongregate-web

Bindings to the Kongregate JavaScript API for Unity: https://kongregate.github.io/kongregate-web/

Kongregate Web API for Unity

This package provides C# bindings to the Kongregate Web API to be used in developing Unity games that will be published on the Kongregate website.

Usage and API documentation

KongregateWeb.BecameReady += () =>
{
    if (KongregateWeb.IsGuest)
    {
        Debug.Log("Player is a guest");
    }
    else
    {
        Debug.Log("Player is logged in as " + KongregateWeb.Username);
    }
};

KongregateWeb.LoggedIn += () =>
{
    Debug.Log("Player is logged in as " + KongregateWeb.Username);
};

Setup and Usage

To include kongregate-web as a Unity package, you'll need to be on Unity 2018.3 or later. kongregate-web is hosted on OpenUPM. Follow the OpenUPM getting started guide if you're not already using it, then run the following command from within your Unity project:

openupm add com.kongregate.kongregate-web

Alternate setup instructions are also available on the docs site.

Once you have added the package to your project you'll also need to setup a custom WebGL template to make the Kongregate JavaScript API available to your game.

kongregate-web's Issues

Remove Json.NET dependency

In order to communicate with the JavaScript API, there are a couple of places we need to convert data to and from JSON. Currently, we are using Json.NET to do the serialization, however doing so forces users to import Json.NET into their project in order to use kongregate-web. Removing this dependency would simplify the process of importing kongregate-web into a project.

The serialization that we need to do are all fairly simple, so we should be able to use Unity's built-in JSON serialization utility with minor modifications to how we communicate with the JavaScript API.

Build documentation and host via gh-pages

Currently the only way to learn the full API for the package is to read through the source code. Ideally, we should be able to generate an online reference for the API and host it publicly via GitHub Pages. As far as I can tell tell there's no "official" documentation generation tool for .NET, so the best options I've found so far are:

• DocFX, which seems to be a relatively new tool for the .NET ecosystem. It's developed publicly as part of the dotnet org on GitHub, so it should probably be the first thing we try.
• Doxygen, old reliable. It's not pretty, it's not especially nice to use, but if we can't get DocFX to work with Unity for whatever reason we'll almost certainly be able to fall back to using Doxygen.

There's already an action for DocFX and one for Doxygen, plus one for updating GitHub Pages sites, so between all of the available tools we should be able to set something up.

Setup build automation

It would be good to setup build automation so that we can verify that all changes compile correctly, and that they build on all platforms. This might be difficult to do, though, since Unity is notoriously hard to do on remote build systems like https://travis-ci.org/.

Include index.html template

The setup instructions in the README direct users to setup a custom index.html template that pulls in the the Kongregate JavaScript API. Reasonable, we should be able to provide a default template that does this for them. That would make it easier for users to get started, and would require less duplicated work between games using kongregate-web.

Missing meta files

Unity version: 2019.3.7f1
Package version: latest

Most of .cs files don't include a .meta file so unity ignores them :S It seems that unity only generates meta files for the ones in /Assets/ folder.

I tried changed /Runtime/ folder perms, but they're changed automatically again when opening the project. Copying the .cs files inside /Assets/ folder so .metas are generated and copying them back to /Runtime/ works.

An idea to replace JSONUtility with Newtonsoft

It would be nice to change JSONUtility to the Newtonsoft for better flexibility, I had problems with PurchaseItems(), which used JsonUtility.ToJson(). Specifically, the method doesn't convert the data when the variables added to it are implemented with the { get; set; }, making the string empty

Add remaining API functions

See https://docs.kongregate.com/v1.0/reference for documentation on all API functions.

• Chat
  • Chat.AddEventListener
  • Chat.ClearMessages
  • Chat.CloseTab
  • Chat.DisplayMessage
  • Chat.ShowTab
• Mtx
  • Mtx.AddEventListener
  • Mtx.InitializeIncentivizedAds
  • Mtx.PurchaseItems
  • Mtx.PurchaseItemsRemote
  • Mtx.RequestItemList
  • Mtx.RequestUserItemList
  • Mtx.ShowIncentivizedAd
  • Mtx.ShowKredPurchaseDialog
  • Mtx.UseItemInstance
• Services
  • Services.Connect (not necessary on web)
  • Services.GetGameAuthToken
  • Services.GetUsername
  • Services.GetUserId
  • Services.IsGuest
  • Services.PrivateMessage
  • Services.ResizeGame
  • Services.ShowInvitationBox
  • Services.ShowFeedPostBox
  • Services.ShowRegistrationBox
  • Services.ShowShoutBox
• SharedContent
  • SharedContent.AddLoadListener
  • SharedContent.Browse
  • SharedContent.Save
• Stats
  • Stats.Submit

Move various structs/enums to separate files

Currently we have a bunch of extra structs/classes/enums defined in KongregateWeb.cs. This is not idiomatic for C#, where it's more common to define each type in its own file. This is minor cleanup that should be quick to do and won't impact the public API of the package.

Move everything into Kongregate.Web namespace

Currently all items defined in this package are in the global namespace. This is a bad practice for a package since it can lead to name collisions and confusion. We should move all items in the package into the Kongregate.Web namespace.