/godot-newgrounds-plugin

Godot Plugin to support NewGrounds API

Primary LanguageGDScriptMIT LicenseMIT

Godot NewGrounds Plugin

The plugin is created to communicate with New Grounds API in version 3 Beta. This repository contains two elements:

  • the plugin - located in folder addons
  • the sample Godot project

Features

  • newgrounds.io API in version v3
  • communication via HTTPS (HTTP with SSL tunnel)
  • API to all described components
  • Allow to use as a Godot node
  • Sample Godot project to present how to use plugin

How to use it

On side of NewGrounds

  1. Go to you project management page
  2. Select API Tools from menu
  3. There is a Notice: The Newgrounds.io API is now in public beta! - click the link to use API v3 in beta mode
  4. Set encryption settings to None (See description in chapter Encryption)
  5. In App Information there's an App Id - remember it.

On side of Godot project (v 3.0.6)

  1. Download plugin to Godot
    • Download this whole project or git clone.
    • To your project copy whole addons folder, which contains addons/newgrounds
    • Move all files from this project to this directory
  2. Configure Godot project
    • Choose Project/Project Settings from the menu
    • In tab Plugins activate NewGround API plugin
    • In tab General go to settings of Network/SSL and select file certs.pem from plugin for Certificates setting
  3. Adding Node
    • In your project scene Add node and select node NewGroundsAPI from HTTPRequest parent
    • For node set Application Id to you App Id from NewGrounds project management page
  4. That's all - just use it.

Simple sample of use

	$NewGroundsAPI.Gateway.getDatetime()
	result = yield($NewGroundsAPI, 'ng_request_complete')
	if $NewGroundsAPI.is_ok(result):
		print('Datetime: ' + str(result.response.datetime))
	else:
		print('Error: ' + result.error)

Organization - How it works

NewGroundsAPI node contains components same, as defined in reference. And in same way there're called functions. But there can be another argues order for used parameters of call (to be more convinient). So, if you want call getDatetime from Gateway component - do it as in the sample. After the request is done you application may keep the work. So, you have to yield for signal ng_request_complete. When signal is emited from plugin it contains a collected information from response or error, if such occures.

The result contains only two fields

  • error - null, if everything is ok or string message with problem
  • result - this contains exactly the structure from result.data, which is a part of JSON response from NewGrounds API.

NewGroundsAPI node settings

This node extends HTTPRequest node.

Parameter Description
Application Id Set up your application Id. It is used to communication with NewGrounds.
Verbose When enabled print out request and response bodies from communication between plugin and NewGrounds. The payload is in JSON format.
Use Threads This setting is ok, if you have application exported not as HTML5. It's automatically disabled by plugin for HTML5.

Sample Godot project

The project may be imported to Godot editor. It is fully prepared to use NewGrounds plugin. NewGrounds for any call needs ApplicationId. For put scores or achieve medals session with logged in user is needed. To log in a user, the passport URL provided by NewGrounds is used. NewGrounds ApplicationId and SessionId are stored in save file on user space.

Some open points

Encryption

Encryption is disabled right now. The reason is I cannot find out right now how to encrypt/decrypt in Godot engine. I found, that some encryption is used inside mbedtils as a third part. I have no idea, how to use it right now.

Anyway - I use communication via HTTPS. It means, that whole communication is done via SSL tunnel.

HTML5 Use Threads disabled

Yes. This flag should be disabled for HTML5. If you force to turn it on, you'll have a supprise with communication error. In the fact, godot engine enables also blocking mode in internally used HttpClient for HTTPRequest. And this produce error for HTML5, which doesn't allow to use blocking mode.

Plugin version changes

Plugin version Changes
1.0.0 Initial version plugin. Uses NG v3 API.
1.0.1 Fix naming mistake.
1.1.0 Create sample usage project.

Licenses

Resource Homepage License
Font grundschrift Grundschrift CC-BY 3.0