{"id":13524762,"url":"https://github.com/Bigaston/pico-8-newgrounds-tutorial","last_synced_at":"2025-04-01T03:32:34.342Z","repository":{"id":98939957,"uuid":"139716077","full_name":"Bigaston/pico-8-newgrounds-tutorial","owner":"Bigaston","description":"A little tutorial to use the Newgrounds medals system with PICO-8","archived":false,"fork":false,"pushed_at":"2018-07-23T21:00:04.000Z","size":941,"stargazers_count":14,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-19T20:47:20.212Z","etag":null,"topics":["javascript-api","newgrounds","newgrounds-medals","pico-8"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bigaston.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-07-04T11:59:23.000Z","updated_at":"2024-11-06T23:50:04.000Z","dependencies_parsed_at":"2024-01-11T14:26:50.133Z","dependency_job_id":null,"html_url":"https://github.com/Bigaston/pico-8-newgrounds-tutorial","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bigaston%2Fpico-8-newgrounds-tutorial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bigaston%2Fpico-8-newgrounds-tutorial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bigaston%2Fpico-8-newgrounds-tutorial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bigaston%2Fpico-8-newgrounds-tutorial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bigaston","download_url":"https://codeload.github.com/Bigaston/pico-8-newgrounds-tutorial/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246578676,"owners_count":20799862,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript-api","newgrounds","newgrounds-medals","pico-8"],"created_at":"2024-08-01T06:01:13.206Z","updated_at":"2025-04-01T03:32:33.981Z","avatar_url":"https://github.com/Bigaston.png","language":"JavaScript","funding_links":["https://ko-fi.com/A0A05WS6"],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"Hello ! Today, I’m going to try to teach you something : how to use the Newgrounds Medals system with your PICO-8 game. \n\n/!\\ 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! /!\\\n\n## What do you need?\n\n- PICO-8 (of course)\n- The [Newgrounds.io Javascript API](https://bitbucket.org/newgrounds/newgrounds.io-for-javascript-html5)\n- A text editor (For this guide, I'm going to use [Brackets](http://brackets.io/))\n- Your own account on Newgrounds\n\n## Setup\n\nThe 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.\n\n![](images/fig1.png)\n*__Fig 1 :__ The content of the `.zip` you download*\n\n\n![](images/fig2.png)\n*__Fig 2 :__ The file you need to drag on your new folder*\n\n## On PICO-8\n\nYou 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).\n\nSo 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.\n\n```Lua\nfunction set_pin(pin,value) --pin : pin between 0 and 127\n\tpoke(0x5f80+pin, value) --value : the value between 0 and 255\nend\n\nfunction get_pin(pin) --pin : the pin do you want to get the value\n\treturn peek(0x5f80+pin)\nend\n```\n\nThe methode I've use is not the best one or the most optimised but it's working and it's not that bad!\n\nWe 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.\n\nSo the function is very simple :\n\n```Lua\nfunction unlock_medals(num) --num : the number of the medals we are\n\tset_pin(0,1)\t\t\t--going to combine the number and the medals\n\tset_pin(1,num)\t\t\t--ID with Javascript\nend\n```\n\nNow, 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.\n\nLet us setup a function to detect that. You have to put it in the `_update` function.\n\n```Lua\nfunction test_medals()\t\n\tif get_pin(0)==2 then --trigger\n\t\tset_pin(0,0) --reset the trigger\n\t\tmed_num=get_pin(1) --get the number of the medals\n\t\tmed_tic=0 --set a tic, for the display function\n\t\t\n\t\tif med_num==1 then --if you had more medals, add it here\n\t\t\tmed_inf={122,\"easy finisher\"}\n\t\t--[[\n\t\telseif med_num==2 then\n\t\t\tmed_inf={sprite to display, \"name of the medals\"} ]]\n\t\tend\n\tend\nend\n```\n\nThe `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.\n\n```Lua\nfunction draw_medals()\n\tif med_num!=0 then --trigger\n\t\tmed_tic+=1 --add 1 to the tic value\n\t\trectfill(-1,116,10+#med_inf[2]*4,128,0) --draw a black background\n\t\trect(-1,116,10+#med_inf[2]*4,128,5)\t--draw a gray square\n\t\tspr(med_inf[1],1,118) --draw the sprite who represent the medals\n\t\tprint(med_inf[2],10,120,5) --print the medals' name\n\t\t\n\t\tif med_tic\u003e=70 then --reset. you can change the duration here\n\t\t\tmed_num=0 --reset\n\t\tend\n\tend\nend\n```\n\nWe just need a last function, to \"init\" the variable. Put it in the `_init` function.\n\n```Lua\nfunction init_medals()\n\tmed_num=0\n\tmed_tin=0\nend\n```\n\nFor 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 :\n\n```\n--basic medals tutorial\n--by bigaston\n\nfunction _init()\n\tinit_medals()\nend\n\nfunction _update()\n\tif btnp(❎) then\n\t\tunlock_medals(1)\n\tend\nend\n\nfunction _draw()\n\tcls()\n\tprint(\"press ❎ to unlock medals\",1,1,7)\n\tdraw_medals()\nend\n\nfunction set_pin(pin,value)\n\tpoke(0x5f80+pin, value)\nend\n\nfunction get_pin(pin)\n\treturn peek(0x5f80+pin)\nend\n\nfunction unlock_medals(num)\n\tset_pin(0,1)\n\tset_pin(1,num)\nend\n\nfunction init_medals()\n\tmed_num=0\n\tmed_tin=0\nend\n\nfunction test_medals()\t\n\tif get_pin(0)==2 then\n\t\tset_pin(0,0)\n\t\tmed_num=get_pin(1)\n\t\tmed_tic=0\n\t\t\n\t\tif med_num==1 then\n\t\t\tmed_inf={1, \"yeah\"}\n\t\tend\n\tend\nend\n\nfunction draw_medals()\n\tif med_num!=0 then\n\t\tmed_tic+=1\n\t\trectfill(-1,116,10+#med_inf[2]*4,128,0)\n\t\trect(-1,116,10+#med_inf[2]*4,128,5)\n\t\tspr(med_inf[1],1,118)\n\t\tprint(med_inf[2],10,120,5)\n\t\t\n\t\tif med_tic\u003e=70 then\n\t\t\tmed_num=0\n\t\tend\n\tend\nend\n```\n\nJust copy this sprite in the first place of your sprite sheet :\n\n```\n[gfx]0808555555555bbbbbb55bbbbbb55bbbb7b55b7b7bb55bb7bbb55bbbbbb555555555[/gfx]\n```\n\nOr, you can just download the cartridge :  \n![](images/ng_medals.p8.png)\n\nTo 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!\n\n## On Newgrounds\n\nNow 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).\n\nNow you have to complete the information about the game (as the picture, the description, ...). We will upload the games files later.\n\nJump 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!`\n\n![](images/fig3.PNG)\n*__Fig 3 :__ Where you have to click*\n\nYou have to get the App ID and the Base64 Encryption Keys.\n\n![](images/fig4.PNG)\n*__Fig 4 :__ The App ID*\n\n![](images/fig5.PNG)\n*__Fig 5 :__ The Encryption Keys*\n\nNote 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.\n\nGo to `Medals` line under the `API Tools` line. Here you can setup the medals.\n\nAdd a new medals.\n\n![](images/fig6.PNG)\n*__Fig 6 :__ Some medals information*\n\nClick 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.\n\n![](images/fig7.PNG)\n*__Fig 7 :__ The Medal ID*\n\nWe have finish with Newgrounds for now. Now we need to use a text editor to edit the `.html` of the game.\n\n## On the Text Editor\n\nSo! 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).\n\nWe need to import the `newgroundsio.js` file. Add a line on the `\u003chead\u003e` part of your document. And you need the JQuery module.\n\n```Javascript\n\u003cscript src=\"https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"bin/newgroundsio.js\" type=\"text/javascript\"\u003e\u003c/script\u003e\n```\n\nNow 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 `\u003cscript\u003e` section before this line : `\u003cscript async type=\"text/javascript\" src=\"your_game.js\"\u003e\u003c/script\u003e`\n\n```Javascript\nvar pico8_gpio = new Array(128); //Enable the PICO-8 GPIO\n\nvar ngio = new Newgrounds.io.core(\"NG App ID\", \"Base64 Encryption Keys\");\n\nfunction onLoggedIn() {\n\tconsole.log(\"Welcome \" + ngio.user.name + \"!\");\n}\n\nfunction onLoginFailed() {\n\tconsole.log(\"There was a problem logging in: \" . ngio.login_error.message );\n}\n\nfunction onLoginCancelled() {\n\tconsole.log(\"The user cancelled the login.\");\n}\n\n/*\n* Before we do anything, we need to get a valid Passport session.  If the player\n* has previously logged in and selected 'remember me', we may have a valid session\n* already saved locally.\n*/\nfunction initSession() {\n\tngio.getValidSession(function() {\n\t\tif (ngio.user) {\n\t\t\t/* \n\t\t\t* If we have a saved session, and it has not expired, \n\t\t\t* we will also have a user object we can access.\n\t\t\t* We can go ahead and run our onLoggedIn handler here.\n\t\t\t*/\n\t\t\tonLoggedIn();\n\t\t} else {\n\t\t\t/*\n\t\t\t* If we didn't have a saved session, or it has expired\n\t\t\t* we should have been given a new one at this point.\n\t\t\t* This is where you would draw a 'sign in' button and\n\t\t\t* have it execute the following requestLogin function.\n\t\t\t*/\n\t\t\trequestLogin();\n\t\t}\n\t});\n}\n\nfunction requestLogin() {\n\tngio.requestLogin(onLoggedIn, onLoginFailed, onLoginCancelled);\n\t/* you should also draw a 'cancel login' buton here */\n}\n\nfunction cancelLogin() {\n\t/*\n\t* This cancels the login request made in the previous function. \n\t* This will also trigger your onLoginCancelled callback.\n\t*/\n\tngio.cancelLoginRequest();\n}\n\nfunction logOut() {\n\tngio.logOut(function() {\n\t\t/*\n\t\t* Because we have to log the player out on the server, you will want\n\t\t* to handle any post-logout stuff in this function, wich fires after\n\t\t* the server has responded.\n\t\t*/\n\t});\n}\n        \ninitSession();\n\n/* vars to record any medals and scoreboards that get loaded */\nvar medals, scoreboards;\n\n/* handle loaded medals */\nfunction onMedalsLoaded(result) {\n\tif (result.success) medals = result.medals;\n}\n\n/* load our medals and scoreboards from the server */\nngio.queueComponent(\"Medal.getList\", {}, onMedalsLoaded);\nngio.executeQueue();\n        \n/* You could use this function to draw the medal notification on-screen */\nfunction onMedalUnlocked(medal) {\n\tconsole.log('MEDAL GET:', medal.name);\n\tif (medal.id==your medal ID) {\n\t\tpico8_gpio[1]=Your medals number (on PICO-8);\n\t}\n    pico8_gpio[0]=2; //Enable the Trigger on PICO-8\n}\n\nfunction UnlockMedal(medal_id) {\n\t/* unlock the medal from the server */\n\tngio.callComponent('Medal.unlock', {id:medal_id}, function(result) {\n\n\t\tif (result.success) onMedalUnlocked(result.medal);\n\n\t});\n}\n        \n(function main(){\n\tif (pico8_gpio[0]==1) {\n\t\tpico8_gpio[0]=0;\n    \tif (pico8_gpio[1]==Your Medal Number) {\n\t\t\tUnlockMedal(Your Medal ID);\n    \t}\n    }\n}()) // call immediately to start the loop\n```\n\nNow 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.\n\nIf you like this tutorial, you can [follow me on Twitter](https://twitter.com/Bigaston), visit [my Itch page](https://bigaston.itch.io).\n\n[![ko-fi](https://www.ko-fi.com/img/donate_sm.png)](https://ko-fi.com/A0A05WS6)\n\n## Sources and thanks\n\n- The Sean explanation of the PICO-8 GPIO ([here](https://www.lexaloffle.com/bbs/?tid=3909))\n- The Newgrounds.io Javascript API, for the Javascript code ([here](https://bitbucket.org/newgrounds/newgrounds.io-for-javascript-html5))\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBigaston%2Fpico-8-newgrounds-tutorial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBigaston%2Fpico-8-newgrounds-tutorial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBigaston%2Fpico-8-newgrounds-tutorial/lists"}