├── README.md ├── file ├── LICENCE.txt ├── bin │ ├── newgroundsio.js │ └── newgroundsio.min.js ├── ng_medals.html ├── ng_medals.js ├── ng_medals.p8 └── src │ ├── core.js │ ├── events.js │ ├── include │ └── aes.js │ ├── license.txt │ ├── model │ ├── call.js │ ├── debug.js │ ├── error.js │ ├── input.js │ ├── medal.js │ ├── output.js │ ├── result.js │ ├── score.js │ ├── scoreboard.js │ ├── session.js │ ├── user.js │ └── usericons.js │ ├── namespaces.js │ ├── sessionloader.js │ └── validators.js └── images ├── fig1.png ├── fig2.png ├── fig3.PNG ├── fig4.PNG ├── fig5.PNG ├── fig6.PNG ├── fig7.PNG └── ng_medals.p8.png /README.md: -------------------------------------------------------------------------------- 1 | Hello ! Today, I’m going to try to teach you something : how to use the Newgrounds Medals system with your PICO-8 game. 2 | 3 | /!\ 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! /!\ 4 | 5 | ## What do you need? 6 | 7 | - PICO-8 (of course) 8 | - The [Newgrounds.io Javascript API](https://bitbucket.org/newgrounds/newgrounds.io-for-javascript-html5) 9 | - A text editor (For this guide, I'm going to use [Brackets](http://brackets.io/)) 10 | - Your own account on Newgrounds 11 | 12 | ## Setup 13 | 14 | The first things you have to do is to download the Newgrounds.io Javascript API ([Download here](https://bitbucket.org/newgrounds/newgrounds.io-for-javascript-html5/downloads/)). Open the `.zip` and drag the `src` and the `bin` in a new folder. 15 | 16 |  17 | *__Fig 1 :__ The content of the `.zip` you download* 18 | 19 | 20 |  21 | *__Fig 2 :__ The file you need to drag on your new folder* 22 | 23 | ## On PICO-8 24 | 25 | 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](https://www.lexaloffle.com/bbs/?tid=3909), but don't worry, I'm going to explain how to simply use it here). 26 | 27 | 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. 28 | 29 | ```Lua 30 | function set_pin(pin,value) --pin : pin between 0 and 127 31 | poke(0x5f80+pin, value) --value : the value between 0 and 255 32 | end 33 | 34 | function get_pin(pin) --pin : the pin do you want to get the value 35 | return peek(0x5f80+pin) 36 | end 37 | ``` 38 | 39 | The methode I've use is not the best one or the most optimised but it's working and it's not that bad! 40 | 41 | 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. 42 | 43 | So the function is very simple : 44 | 45 | ```Lua 46 | function unlock_medals(num) --num : the number of the medals we are 47 | set_pin(0,1) --going to combine the number and the medals 48 | set_pin(1,num) --ID with Javascript 49 | end 50 | ``` 51 | 52 | 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. 53 | 54 | Let us setup a function to detect that. You have to put it in the `_update` function. 55 | 56 | ```Lua 57 | function test_medals() 58 | if get_pin(0)==2 then --trigger 59 | set_pin(0,0) --reset the trigger 60 | med_num=get_pin(1) --get the number of the medals 61 | med_tic=0 --set a tic, for the display function 62 | 63 | if med_num==1 then --if you had more medals, add it here 64 | med_inf={122,"easy finisher"} 65 | --[[ 66 | elseif med_num==2 then 67 | med_inf={sprite to display, "name of the medals"} ]] 68 | end 69 | end 70 | end 71 | ``` 72 | 73 | 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. 74 | 75 | ```Lua 76 | function draw_medals() 77 | if med_num!=0 then --trigger 78 | med_tic+=1 --add 1 to the tic value 79 | rectfill(-1,116,10+#med_inf[2]*4,128,0) --draw a black background 80 | rect(-1,116,10+#med_inf[2]*4,128,5) --draw a gray square 81 | spr(med_inf[1],1,118) --draw the sprite who represent the medals 82 | print(med_inf[2],10,120,5) --print the medals' name 83 | 84 | if med_tic>=70 then --reset. you can change the duration here 85 | med_num=0 --reset 86 | end 87 | end 88 | end 89 | ``` 90 | 91 | We just need a last function, to "init" the variable. Put it in the `_init` function. 92 | 93 | ```Lua 94 | function init_medals() 95 | med_num=0 96 | med_tin=0 97 | end 98 | ``` 99 | 100 | 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 : 101 | 102 | ``` 103 | --basic medals tutorial 104 | --by bigaston 105 | 106 | function _init() 107 | init_medals() 108 | end 109 | 110 | function _update() 111 | if btnp(❎) then 112 | unlock_medals(1) 113 | end 114 | end 115 | 116 | function _draw() 117 | cls() 118 | print("press ❎ to unlock medals",1,1,7) 119 | draw_medals() 120 | end 121 | 122 | function set_pin(pin,value) 123 | poke(0x5f80+pin, value) 124 | end 125 | 126 | function get_pin(pin) 127 | return peek(0x5f80+pin) 128 | end 129 | 130 | function unlock_medals(num) 131 | set_pin(0,1) 132 | set_pin(1,num) 133 | end 134 | 135 | function init_medals() 136 | med_num=0 137 | med_tin=0 138 | end 139 | 140 | function test_medals() 141 | if get_pin(0)==2 then 142 | set_pin(0,0) 143 | med_num=get_pin(1) 144 | med_tic=0 145 | 146 | if med_num==1 then 147 | med_inf={1, "yeah"} 148 | end 149 | end 150 | end 151 | 152 | function draw_medals() 153 | if med_num!=0 then 154 | med_tic+=1 155 | rectfill(-1,116,10+#med_inf[2]*4,128,0) 156 | rect(-1,116,10+#med_inf[2]*4,128,5) 157 | spr(med_inf[1],1,118) 158 | print(med_inf[2],10,120,5) 159 | 160 | if med_tic>=70 then 161 | med_num=0 162 | end 163 | end 164 | end 165 | ``` 166 | 167 | Just copy this sprite in the first place of your sprite sheet : 168 | 169 | ``` 170 | [gfx]0808555555555bbbbbb55bbbbbb55bbbb7b55b7b7bb55bb7bbb55bbbbbb555555555[/gfx] 171 | ``` 172 | 173 | Or, you can just download the cartridge : 174 |  175 | 176 | 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! 177 | 178 | ## On Newgrounds 179 | 180 | Now we are going to setup the game on Newgrounds to have access to the API. Create a new games [here](https://www.newgrounds.com/projects/games). 181 | 182 | Now you have to complete the information about the game (as the picture, the description, ...). We will upload the games files later. 183 | 184 | 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!` 185 | 186 |  187 | *__Fig 3 :__ Where you have to click* 188 | 189 | You have to get the App ID and the Base64 Encryption Keys. 190 | 191 |  192 | *__Fig 4 :__ The App ID* 193 | 194 |  195 | *__Fig 5 :__ The Encryption Keys* 196 | 197 | 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. 198 | 199 | Go to `Medals` line under the `API Tools` line. Here you can setup the medals. 200 | 201 | Add a new medals. 202 | 203 |  204 | *__Fig 6 :__ Some medals information* 205 | 206 | 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. 207 | 208 |  209 | *__Fig 7 :__ The Medal ID* 210 | 211 | We have finish with Newgrounds for now. Now we need to use a text editor to edit the `.html` of the game. 212 | 213 | ## On the Text Editor 214 | 215 | 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](https://bitbucket.org/newgrounds/newgrounds.io-for-javascript-html5). 216 | 217 | We need to import the `newgroundsio.js` file. Add a line on the `
` part of your document. And you need the JQuery module. 218 | 219 | ```Javascript 220 | 221 | 222 | ``` 223 | 224 | 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 `` 225 | 226 | ```Javascript 227 | var pico8_gpio = new Array(128); //Enable the PICO-8 GPIO 228 | 229 | var ngio = new Newgrounds.io.core("NG App ID", "Base64 Encryption Keys"); 230 | 231 | function onLoggedIn() { 232 | console.log("Welcome " + ngio.user.name + "!"); 233 | } 234 | 235 | function onLoginFailed() { 236 | console.log("There was a problem logging in: " . ngio.login_error.message ); 237 | } 238 | 239 | function onLoginCancelled() { 240 | console.log("The user cancelled the login."); 241 | } 242 | 243 | /* 244 | * Before we do anything, we need to get a valid Passport session. If the player 245 | * has previously logged in and selected 'remember me', we may have a valid session 246 | * already saved locally. 247 | */ 248 | function initSession() { 249 | ngio.getValidSession(function() { 250 | if (ngio.user) { 251 | /* 252 | * If we have a saved session, and it has not expired, 253 | * we will also have a user object we can access. 254 | * We can go ahead and run our onLoggedIn handler here. 255 | */ 256 | onLoggedIn(); 257 | } else { 258 | /* 259 | * If we didn't have a saved session, or it has expired 260 | * we should have been given a new one at this point. 261 | * This is where you would draw a 'sign in' button and 262 | * have it execute the following requestLogin function. 263 | */ 264 | requestLogin(); 265 | } 266 | }); 267 | } 268 | 269 | function requestLogin() { 270 | ngio.requestLogin(onLoggedIn, onLoginFailed, onLoginCancelled); 271 | /* you should also draw a 'cancel login' buton here */ 272 | } 273 | 274 | function cancelLogin() { 275 | /* 276 | * This cancels the login request made in the previous function. 277 | * This will also trigger your onLoginCancelled callback. 278 | */ 279 | ngio.cancelLoginRequest(); 280 | } 281 | 282 | function logOut() { 283 | ngio.logOut(function() { 284 | /* 285 | * Because we have to log the player out on the server, you will want 286 | * to handle any post-logout stuff in this function, wich fires after 287 | * the server has responded. 288 | */ 289 | }); 290 | } 291 | 292 | initSession(); 293 | 294 | /* vars to record any medals and scoreboards that get loaded */ 295 | var medals, scoreboards; 296 | 297 | /* handle loaded medals */ 298 | function onMedalsLoaded(result) { 299 | if (result.success) medals = result.medals; 300 | } 301 | 302 | /* load our medals and scoreboards from the server */ 303 | ngio.queueComponent("Medal.getList", {}, onMedalsLoaded); 304 | ngio.executeQueue(); 305 | 306 | /* You could use this function to draw the medal notification on-screen */ 307 | function onMedalUnlocked(medal) { 308 | console.log('MEDAL GET:', medal.name); 309 | if (medal.id==your medal ID) { 310 | pico8_gpio[1]=Your medals number (on PICO-8); 311 | } 312 | pico8_gpio[0]=2; //Enable the Trigger on PICO-8 313 | } 314 | 315 | function UnlockMedal(medal_id) { 316 | /* unlock the medal from the server */ 317 | ngio.callComponent('Medal.unlock', {id:medal_id}, function(result) { 318 | 319 | if (result.success) onMedalUnlocked(result.medal); 320 | 321 | }); 322 | } 323 | 324 | (function main(){ 325 | if (pico8_gpio[0]==1) { 326 | pico8_gpio[0]=0; 327 | if (pico8_gpio[1]==Your Medal Number) { 328 | UnlockMedal(Your Medal ID); 329 | } 330 | } 331 | }()) // call immediately to start the loop 332 | ``` 333 | 334 | 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. 335 | 336 | If you like this tutorial, you can [follow me on Twitter](https://twitter.com/Bigaston), visit [my Itch page](https://bigaston.itch.io). 337 | 338 | [](https://ko-fi.com/A0A05WS6) 339 | 340 | ## Sources and thanks 341 | 342 | - The Sean explanation of the PICO-8 GPIO ([here](https://www.lexaloffle.com/bbs/?tid=3909)) 343 | - The Newgrounds.io Javascript API, for the Javascript code ([here](https://bitbucket.org/newgrounds/newgrounds.io-for-javascript-html5)) 344 | 345 | 346 | -------------------------------------------------------------------------------- /file/LICENCE.txt: -------------------------------------------------------------------------------- 1 | Newgrounds.IO Licence 2 | 3 | Copyright (c) 2015 Newgrounds Inc. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 6 | 7 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 8 | 9 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -------------------------------------------------------------------------------- /file/bin/newgroundsio.min.js: -------------------------------------------------------------------------------- 1 | "undefined"==typeof Newgrounds&&(Newgrounds={}),Newgrounds.io={GATEWAY_URI:"//newgrounds.io/gateway_v3.php"},Newgrounds.io.events={},Newgrounds.io.call_validators={},Newgrounds.io.model={checkStrictValue:function(e,t,r,n,o,s,i){if("mixed"==n)return!0 2 | if(null===r||"undefined"==typeof r)return!0 3 | if(n&&r.constructor===n)return!0 4 | if(n==Boolean&&r.constructor===Number)return!0 5 | if(o&&r.constructor===Newgrounds.io.model[o])return!0 6 | if(r.constructor===Array&&(s||i)){for(var u=0;u>>6*(3-v)&63));if(l=t.charAt(64))for(;d.length%4;)d.push(l);return d.join("")},parse:function(d){var l=d.length,s=this._map,t=s.charAt(64);t&&(t=d.indexOf(t),-1!=t&&(l=t));for(var t=[],r=0,w=0;w<
15 | l;w++)if(w%4){var v=s.indexOf(d.charAt(w-1))<<2*(w%4),b=s.indexOf(d.charAt(w))>>>6-2*(w%4);t[r>>>2]|=(v|b)<<24-8*(r%4);r++}return p.create(t,r)},_map:"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/="}})();
16 | (function(u){function p(b,n,a,c,e,j,k){b=b+(n&a|~n&c)+e+k;return(b<>>2]&255}};d.BlockCipher=v.extend({cfg:v.cfg.extend({mode:b,padding:q}),reset:function(){v.reset.call(this);var a=this.cfg,b=a.iv,a=a.mode;if(this._xformMode==this._ENC_XFORM_MODE)var c=a.createEncryptor;else c=a.createDecryptor,this._minBufferSize=1;this._mode=c.call(a,
28 | this,b&&b.words)},_doProcessBlock:function(a,b){this._mode.processBlock(a,b)},_doFinalize:function(){var a=this.cfg.padding;if(this._xformMode==this._ENC_XFORM_MODE){a.pad(this._data,this.blockSize);var b=this._process(!0)}else b=this._process(!0),a.unpad(b);return b},blockSize:4});var n=d.CipherParams=l.extend({init:function(a){this.mixIn(a)},toString:function(a){return(a||this.formatter).stringify(this)}}),b=(p.format={}).OpenSSL={stringify:function(a){var b=a.ciphertext;a=a.salt;return(a?s.create([1398893684,
29 | 1701076831]).concat(a).concat(b):b).toString(r)},parse:function(a){a=r.parse(a);var b=a.words;if(1398893684==b[0]&&1701076831==b[1]){var c=s.create(b.slice(2,4));b.splice(0,4);a.sigBytes-=16}return n.create({ciphertext:a,salt:c})}},a=d.SerializableCipher=l.extend({cfg:l.extend({format:b}),encrypt:function(a,b,c,d){d=this.cfg.extend(d);var l=a.createEncryptor(c,d);b=l.finalize(b);l=l.cfg;return n.create({ciphertext:b,key:c,iv:l.iv,algorithm:a,mode:l.mode,padding:l.padding,blockSize:a.blockSize,formatter:d.format})},
30 | decrypt:function(a,b,c,d){d=this.cfg.extend(d);b=this._parse(b,d.format);return a.createDecryptor(c,d).finalize(b.ciphertext)},_parse:function(a,b){return"string"==typeof a?b.parse(a,this):a}}),p=(p.kdf={}).OpenSSL={execute:function(a,b,c,d){d||(d=s.random(8));a=w.create({keySize:b+c}).compute(a,d);c=s.create(a.words.slice(b),4*c);a.sigBytes=4*b;return n.create({key:a,iv:c,salt:d})}},c=d.PasswordBasedCipher=a.extend({cfg:a.cfg.extend({kdf:p}),encrypt:function(b,c,d,l){l=this.cfg.extend(l);d=l.kdf.execute(d,
31 | b.keySize,b.ivSize);l.iv=d.iv;b=a.encrypt.call(this,b,c,d.key,l);b.mixIn(d);return b},decrypt:function(b,c,d,l){l=this.cfg.extend(l);c=this._parse(c,l.format);d=l.kdf.execute(d,b.keySize,b.ivSize,c.salt);l.iv=d.iv;return a.decrypt.call(this,b,c,d.key,l)}})}();
32 | (function(){for(var u=CryptoJS,p=u.lib.BlockCipher,d=u.algo,l=[],s=[],t=[],r=[],w=[],v=[],b=[],x=[],q=[],n=[],a=[],c=0;256>c;c++)a[c]=128>c?c<<1:c<<1^283;for(var e=0,j=0,c=0;256>c;c++){var k=j^j<<1^j<<2^j<<3^j<<4,k=k>>>8^k&255^99;l[e]=k;s[k]=e;var z=a[e],F=a[z],G=a[F],y=257*a[k]^16843008*k;t[e]=y<<24|y>>>8;r[e]=y<<16|y>>>16;w[e]=y<<8|y>>>24;v[e]=y;y=16843009*G^65537*F^257*z^16843008*e;b[k]=y<<24|y>>>8;x[k]=y<<16|y>>>16;q[k]=y<<8|y>>>24;n[k]=y;e?(e=z^a[a[a[G^z]]],j^=a[a[j]]):e=j=1}var H=[0,1,2,4,8,
33 | 16,32,64,128,27,54],d=d.AES=p.extend({_doReset:function(){for(var a=this._key,c=a.words,d=a.sigBytes/4,a=4*((this._nRounds=d+6)+1),e=this._keySchedule=[],j=0;j>>24]<<24|l[k>>>16&255]<<16|l[k>>>8&255]<<8|l[k&255]):(k=k<<8|k>>>24,k=l[k>>>24]<<24|l[k>>>16&255]<<16|l[k>>>8&255]<<8|l[k&255],k^=H[j/d|0]<<24);e[j]=e[j-d]^k}c=this._invKeySchedule=[];for(d=0;dd||4>=j?k:b[l[k>>>24]]^x[l[k>>>16&255]]^q[l[k>>>
34 | 8&255]]^n[l[k&255]]},encryptBlock:function(a,b){this._doCryptBlock(a,b,this._keySchedule,t,r,w,v,l)},decryptBlock:function(a,c){var d=a[c+1];a[c+1]=a[c+3];a[c+3]=d;this._doCryptBlock(a,c,this._invKeySchedule,b,x,q,n,s);d=a[c+1];a[c+1]=a[c+3];a[c+3]=d},_doCryptBlock:function(a,b,c,d,e,j,l,f){for(var m=this._nRounds,g=a[b]^c[0],h=a[b+1]^c[1],k=a[b+2]^c[2],n=a[b+3]^c[3],p=4,r=1;r