Skip to content

Latest commit

 

History

History
102 lines (86 loc) · 4.19 KB

README.md

File metadata and controls

102 lines (86 loc) · 4.19 KB
Raw

REST-love

This is a common set of things for calling REST APIs in Love, it supports Android, Web, Linux and Windows. Every REST API is implemented with async functionality, so, it is running on another thread in every platform The best thing about that is that every platform doesn't need any additional code (Except for Web that you need to add the script tag)!

Setting up REST-love

  • Clone it on your folder
git clone https://github.com/MrcSnm/REST-love.git
  • Enter on it
cd REST-love
  • Update every submodule
git submodule update --init --recursive
  • Now just require "REST", it defines a global named REST
  • If you wish to use module-loader into your project, just delete the require module-loader from REST.lua (First line)

Simple Example

Here is a simple example of using it in a love-game. Let's imagine you have recursive-cloned this repo to a sub-folder in your game: lib/REST-love:

-- this lets you require things with different paths other than root
require "lib.REST-love.module-loader"

-- this adds REST global
requireFromLib("lib/REST-love", "REST")

function love.load()
  REST.get("https://mycoolserver.com/api", nil, function(data)
   -- Do something here with data. It's text.
  end)
end

function love.update(dt)
  -- this is needed to trigger pending callbacks
  -- it's wrapped with pcall to prevent it from crashing game
  pcall(function() REST.retrieve(dt) end)
end

AsyncLoader

AsyncLoader(Actually CoroutineLoader) is meant to be used by the LoadBar module, but you can extend its use yourself, you can use that to do any heavy and synchronous operation for thiner operations, this is a Singleton, don't extend it unless adapting it first, call it directly

LoadBar

A simple loading bar that uses the AsyncLoader module, there is a default LoadBar made with primitives if no front and back image is provided, for using it, simply do

loadBarInstance.addContentToLoad(loadFunction, onLoad, contentName)

If you wish, in the content name you can pass a special character that will be replaced by the current load progress, a simple use-case is:

require "loadbar"
loadBarInstance = LoadBar:new(width, height, frontTexture, backTexture)
imgs = {}
loadBarInstance.addContentToLoad(function()
    imgs["myImg"] = love.graphics.newImage("myImg.png")
end, nil, "Loading myImg: $")

Then just add loadBarInstance:update(dt) on your update function And loadBarInstance:render as the last thing to render on your draw function

Module-Loader

This is a really good thing when you just copy/paste some lib into your project and you need to import it without doing any kind of code replacement, e.g:

local js = requireFromLib("js", "js")
local req = requireFromLib("luajit-request", "luajit-request")

This is useful as "js" or "luajit-request" may require other libs inside it's own project, so, you won't need to adapt anything

JS

This is a project dependency, REST calls will be adapted to the Love.js-Api-Player Good thing about this is that you won't need to call yourself XMLHttpRequest

REST

Where the project magic happens, it has its own defined behavior for Default(Android and Linux), Windows and Web, every REST function has async support, and, for actually 'loading'(actually used for onLoad callback) the request data, you need to include in your love.update function

REST.retrieve(dt)

If you want it to be sync(or execute any action), just make it return if rest.update returns true:

if(REST.retrieve(dt)) then
    return
end

Notes

  • Please, notice that if you're already using Love.js Api-Player, there will be no need to call JS.retrieveData(dt)
  • Inline sync is implemented for Default and Windows, but as it is still not supported on Web, as it always uses the Web thread for making the http request, I did not implement any function for alternating inline sync and async, however, if you do wish to use, just enter in the target (default or win) and change
  • I don't really remember if I'm using x32 or x64 libcurl, I believe it is x32(because filesize)