Awesome
Hello ! Today, I’m going to try to teach you something : how to use the Newgrounds Medals system with your PICO-8 game.
/!\ I'm going to explain you how I've setup medals for my game, Rush. I haven't used all the possibilities of the medals, therefore the system can be improved. But as a basic integration, this is very good! /!\
What do you need?
- PICO-8 (of course)
- The Newgrounds.io Javascript API
- A text editor (For this guide, I'm going to use Brackets)
- Your own account on Newgrounds
Setup
The first things you have to do is to download the Newgrounds.io Javascript API (Download here). Open the .zip and drag the src and the bin in a new folder.
Fig 1 : The content of the .zip you download
Fig 2 : The file you need to drag on your new folder
On PICO-8
You have your game on PICO-8. For the transfer, we are going to use the GPIO system (if you don't know how it's working, you can read the Sean explanation, but don't worry, I'm going to explain how to simply use it here).
So in PICO-8 you can use 128 pin which can get a value between 0 and 255. Normaly it's for the Raspberry Pi and the Pocketchip, but you can get it too thanks to Javascript! You have to poke value on the adress from 0x5f80 to 0x6000. We are going to setup two small functions, that way it'll be easier to peek and poke the value.
function set_pin(pin,value) --pin : pin between 0 and 127
poke(0x5f80+pin, value) --value : the value between 0 and 255
end
function get_pin(pin) --pin : the pin do you want to get the value
return peek(0x5f80+pin)
end
The methode I've use is not the best one or the most optimised but it's working and it's not that bad!
We are going to setup a second function, with this function you can ask to the API to unlock a new function. We are going to use the pin "0" to say we need to unlock a medals, and the pin 1 to say which medal we want to unlock. I use 2 pin because if you want to create another system, like a sharable score, you can change the value of the pin 0 so you don't have conflicts with that.
So the function is very simple :
function unlock_medals(num) --num : the number of the medals we are
set_pin(0,1) --going to combine the number and the medals
set_pin(1,num) --ID with Javascript
end
Now, we are going to setup the Unlock Medals sound and visual effect in PICO-8. We are going to use the pin 0 for the trigger and the pin 1 for the number of the medals.
Let us setup a function to detect that. You have to put it in the _update function.
function test_medals()
if get_pin(0)==2 then --trigger
set_pin(0,0) --reset the trigger
med_num=get_pin(1) --get the number of the medals
med_tic=0 --set a tic, for the display function
if med_num==1 then --if you had more medals, add it here
med_inf={122,"easy finisher"}
--[[
elseif med_num==2 then
med_inf={sprite to display, "name of the medals"} ]]
end
end
end
The med_inf variable contains the information about the medals, this information can be use in the next function, the draw_medals function. You have to put this function in the last line of _draw function of PICO-8.
function draw_medals()
if med_num!=0 then --trigger
med_tic+=1 --add 1 to the tic value
rectfill(-1,116,10+#med_inf[2]*4,128,0) --draw a black background
rect(-1,116,10+#med_inf[2]*4,128,5) --draw a gray square
spr(med_inf[1],1,118) --draw the sprite who represent the medals
print(med_inf[2],10,120,5) --print the medals' name
if med_tic>=70 then --reset. you can change the duration here
med_num=0 --reset
end
end
end
We just need a last function, to "init" the variable. Put it in the _init function.
function init_medals()
med_num=0
med_tin=0
end
For the test, we are going to setup a basic interaction to test the medals. When you press the ❎ button, we unlock a new medal. So all of our PICO-8 Code is :
--basic medals tutorial
--by bigaston
function _init()
init_medals()
end
function _update()
if btnp(❎) then
unlock_medals(1)
end
end
function _draw()
cls()
print("press ❎ to unlock medals",1,1,7)
draw_medals()
end
function set_pin(pin,value)
poke(0x5f80+pin, value)
end
function get_pin(pin)
return peek(0x5f80+pin)
end
function unlock_medals(num)
set_pin(0,1)
set_pin(1,num)
end
function init_medals()
med_num=0
med_tin=0
end
function test_medals()
if get_pin(0)==2 then
set_pin(0,0)
med_num=get_pin(1)
med_tic=0
if med_num==1 then
med_inf={1, "yeah"}
end
end
end
function draw_medals()
if med_num!=0 then
med_tic+=1
rectfill(-1,116,10+#med_inf[2]*4,128,0)
rect(-1,116,10+#med_inf[2]*4,128,5)
spr(med_inf[1],1,118)
print(med_inf[2],10,120,5)
if med_tic>=70 then
med_num=0
end
end
end
Just copy this sprite in the first place of your sprite sheet :
[gfx]0808555555555bbbbbb55bbbbbb55bbbb7b55b7b7bb55bb7bbb55bbbbbb555555555[/gfx]
Or, you can just download the cartridge :
To finish, just export the game in HTML5. After that, just copy your .html and .js file and it's done! You have finished the job with PICO-8!
On Newgrounds
Now we are going to setup the game on Newgrounds to have access to the API. Create a new games here.
Now you have to complete the information about the game (as the picture, the description, ...). We will upload the games files later.
Jump to the API Tool line (on the left). Read and aprove the text. Now just click on Click here to use the Newgrounds.io API for this game!
Fig 3 : Where you have to click
You have to get the App ID and the Base64 Encryption Keys.
Fig 4 : The App ID
Fig 5 : The Encryption Keys
Note it somewhere, you'll need it later. Now we are going to setup the medals. We have already made one medals in PICO-8 so we are going to add it on Newgrounds.
Go to Medals line under the API Tools line. Here you can setup the medals.
Add a new medals.
Fig 6 : Some medals information
Click on Submit and take the Medals ID. If you want the medals to appear on the game's page, you have to unlock it once with your game.
Fig 7 : The Medal ID
We have finish with Newgrounds for now. Now we need to use a text editor to edit the .html of the game.
On the Text Editor
So! We have to edit the .html export by PICO-8. I'm going to share with you some premade code. You can find the Newgrounds part on the bitbucket page of the Javascript API.
We need to import the newgroundsio.js file. Add a line on the <head> part of your document. And you need the JQuery module.
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
<script src="bin/newgroundsio.js" type="text/javascript"></script>
Now I'm going to share you a premade code that you can use to enable medals. You can read the comment to understand how it's work. You just have to put this code on <script> section before this line : <script async type="text/javascript" src="your_game.js"></script>
var pico8_gpio = new Array(128); //Enable the PICO-8 GPIO
var ngio = new Newgrounds.io.core("NG App ID", "Base64 Encryption Keys");
function onLoggedIn() {
console.log("Welcome " + ngio.user.name + "!");
}
function onLoginFailed() {
console.log("There was a problem logging in: " . ngio.login_error.message );
}
function onLoginCancelled() {
console.log("The user cancelled the login.");
}
/*
* Before we do anything, we need to get a valid Passport session. If the player
* has previously logged in and selected 'remember me', we may have a valid session
* already saved locally.
*/
function initSession() {
ngio.getValidSession(function() {
if (ngio.user) {
/*
* If we have a saved session, and it has not expired,
* we will also have a user object we can access.
* We can go ahead and run our onLoggedIn handler here.
*/
onLoggedIn();
} else {
/*
* If we didn't have a saved session, or it has expired
* we should have been given a new one at this point.
* This is where you would draw a 'sign in' button and
* have it execute the following requestLogin function.
*/
requestLogin();
}
});
}
function requestLogin() {
ngio.requestLogin(onLoggedIn, onLoginFailed, onLoginCancelled);
/* you should also draw a 'cancel login' buton here */
}
function cancelLogin() {
/*
* This cancels the login request made in the previous function.
* This will also trigger your onLoginCancelled callback.
*/
ngio.cancelLoginRequest();
}
function logOut() {
ngio.logOut(function() {
/*
* Because we have to log the player out on the server, you will want
* to handle any post-logout stuff in this function, wich fires after
* the server has responded.
*/
});
}
initSession();
/* vars to record any medals and scoreboards that get loaded */
var medals, scoreboards;
/* handle loaded medals */
function onMedalsLoaded(result) {
if (result.success) medals = result.medals;
}
/* load our medals and scoreboards from the server */
ngio.queueComponent("Medal.getList", {}, onMedalsLoaded);
ngio.executeQueue();
/* You could use this function to draw the medal notification on-screen */
function onMedalUnlocked(medal) {
console.log('MEDAL GET:', medal.name);
if (medal.id==your medal ID) {
pico8_gpio[1]=Your medals number (on PICO-8);
}
pico8_gpio[0]=2; //Enable the Trigger on PICO-8
}
function UnlockMedal(medal_id) {
/* unlock the medal from the server */
ngio.callComponent('Medal.unlock', {id:medal_id}, function(result) {
if (result.success) onMedalUnlocked(result.medal);
});
}
(function main(){
if (pico8_gpio[0]==1) {
pico8_gpio[0]=0;
if (pico8_gpio[1]==Your Medal Number) {
UnlockMedal(Your Medal ID);
}
}
}()) // call immediately to start the loop
Now you just have to rename your HTML file to index.html, create a ZIP Archive with your .js file, your .html file, the bin and src folder. Just upload the whole archive on Newgrounds and it's done! Just unlock the medals to validate it.
If you like this tutorial, you can follow me on Twitter, visit my Itch page.
