├── Makefile
├── Readme.md
├── track.html
├── track.lua
├── track_test.html
└── track_test.js


/Makefile:
--------------------------------------------------------------------------------
 1 | # Given 'track.lua', prepend a header to create 'track_test.p8'.
 2 | track_test.p8: track.lua
 3 | 	@echo 'pico-8 cartridge // http://www.pico-8.com' > track_test.p8
 4 | 	@echo 'version 16' >> track_test.p8
 5 | 	@echo '__lua__' >> track_test.p8
 6 | 	@cat track.lua >> track_test.p8
 7 | 
 8 | # Remove generated files.
 9 | clean:
10 | 	@rm track_test.p8
11 | 


--------------------------------------------------------------------------------
/Readme.md:
--------------------------------------------------------------------------------
 1 | # analytics-pico8
 2 | 
 3 | <img src="https://user-images.githubusercontent.com/914228/43900090-aaf02800-9b98-11e8-931e-c82e0c3ed44b.png" alt="" width="500px"></img>
 4 | 
 5 | Analytics for your PICO-8 game, powered by Segment.
 6 | 
 7 | See a video demo of a fully-instrumented Jelpi demo: <a href="https://www.youtube.com/watch?v=_SQ2SiSPj5w" target="_blank"><code>View Link</code></a>
 8 | 
 9 | > *Note:* I created this project for Segment Hack Week. Consider it alpha quality, since it doesn't support the functionality of [Segment's official sources](https://segment.com/docs/sources/).
10 | 
11 | <br>
12 | 
13 | ## Wait, what?
14 | 
15 | PICO-8 is a tool that you can use to create (and distribute) small, retro-style games. It's like Unity – the game engine – but with more design constraints to encourage you to keep your project scope small. Admittedly, it's kinda nerdy.
16 | 
17 | Segment is an awesome analytics product that intends to be your **customer data infrastructure**. You can use Segment to track user events, send events out to hundreds of analytics tools automatically, and use these tools to derive insights from your data. Armed with these insights, you can find ways to improve your game's design.
18 | 
19 | <br>
20 | 
21 | ## Awesome, how do I use it?
22 | 
23 | ### Learn
24 | 
25 | If you're new to PICO-8, I suggest skimming the [manual](https://www.lexaloffle.com/pico-8.php?page=manual) for an overview.
26 | 
27 | <br>
28 | 
29 | ### Copy and paste
30 | 
31 | Copy and paste [`track.lua`](./track.lua) into your PICO-8 game.
32 | 
33 | <br>
34 | 
35 | ### API
36 | 
37 | `track.lua` will expose a single function `track()` globally. To use:
38 | 
39 | ```lua
40 | -- API:
41 | track(event, properties?)
42 | 
43 | -- Example:
44 | track('Level Cleared', {
45 |   level             = 4,
46 |   time              = 39.2,
47 |   found_secret_room = true,
48 | })
49 | ```
50 | 
51 | You can track as many events and properties as you want, subject to PICO-8's char and token limits. `track.lua` serializes `track()` calls to PICO-8's [GPIO pins](http://pico-8.wikia.com/wiki/GPIO), so be aware that you have 128 bytes of info per `track()` call.
52 | 
53 | <br>
54 | 
55 | ### Export, insert `track.html` and `analytics.js`
56 | 
57 | In the PICO-8 console, export your game to HTML5:
58 | 
59 | ```sh
60 | > EXPORT YOUR_GAME.HTML
61 | ```
62 | 
63 | Find your `<script>` tag in the generated HTML. It should look like this:
64 | 
65 | ```html
66 | <script async type="text/javascript" src="your_game.js"></script>
67 | ```
68 | 
69 | Above it, insert the contents of [`track.html`](./track.html), then the `analytics.js` snippet ([view here](https://segment.com/docs/sources/website/analytics.js/quickstart/)). Verify that your Segment write key is present – check the setup instructions for details.
70 | 
71 | You can reference [`track_test.html`](./track_test.html) as an example.
72 | 
73 | <br>
74 | 
75 | ### Celebrate
76 | 
77 | If all goes well, you should see events flowing through to Segment's Debugger:
78 | 
79 | <img width="1300" alt="screen shot 2018-08-08 at 1 50 50 pm" src="https://user-images.githubusercontent.com/914228/43863611-1736cca8-9b12-11e8-97e4-f07de2bdf88c.png">
80 | 
81 | You now have the ability to understand how players interact with your game's design! Go forth and inform your designs with data.
82 | 
83 | <br>
84 | 
85 | ## Feedback
86 | 
87 | Please open an [issue](https://github.com/segmentio/analytics-pico8/issues/new).
88 | 
89 | <br>
90 | 
91 | ## License
92 | 
93 | `analytics-pico8` is released under the MIT License.
94 | 
95 | Copyright © 2018 Segment.io, Inc.
96 | 


--------------------------------------------------------------------------------
/track.html:
--------------------------------------------------------------------------------
 1 | <script>
 2 |   ;(function() {
 3 |     var index = 0
 4 |     var chars = ' !"#%\'()*+,-./0123456789:;<=>?abcdefghijklmnopqrstuvwxyz[]^_{~}'
 5 |     function readByte(arr) {
 6 |       var b = arr[index]
 7 |       index++
 8 |       return b
 9 |     }
10 |     function readChar(arr) {
11 |       var charCode = arr[index]
12 |       index++
13 |       return chars[charCode-1]
14 |     }
15 |     function readString(arr) {
16 |       var strlen = readByte(arr)
17 |       var str = ''
18 |       for (var i = 0; i < strlen; i++) str += readChar(arr)
19 |       return str
20 |     }
21 |     function readNum(arr) {
22 |       var numStr = readString(arr)
23 |       return parseInt(numStr, 10)
24 |     }
25 |     function readBool(arr) {
26 |       return readByte(arr) > 0
27 |     }
28 |     function readValue(arr) {
29 |       var type = readByte(arr)
30 |       if (type === 0) return readBool(arr)
31 |       if (type === 1) return readNum(arr)
32 |       if (type === 2) return readString(arr)
33 |       throw new Error('Failed read.')
34 |     }
35 |     function onTrack(o, onTrack) {
36 |       return new Proxy(o, {
37 |         set: function(target, property, value) {
38 |           if (value === 255) {
39 |             // Find "end-of-track" index.
40 |             var End = Number(property)
41 |             // Read event name.
42 |             var event = readString(target)
43 |             // Read properties.
44 |             var properties = {}
45 |             while (index < End) {
46 |               var key = readString(target)
47 |               var value = readValue(target)
48 |               properties[key] = value
49 |             }
50 |             // Reset offset.
51 |             index = 0
52 |             // Call onTrack handler.
53 |             onTrack(event, properties)
54 |           }
55 |           target[property] = value
56 |           return true
57 |         },
58 |       })
59 |     }
60 |     pico8_gpio = onTrack(new Array(128), function(event, properties) {
61 |       analytics.track(event, properties)
62 |     })
63 |   })()
64 | </script>
65 | 


--------------------------------------------------------------------------------
/track.lua:
--------------------------------------------------------------------------------
 1 | do
 2 |   local chars = ' !"#%\'()*+,-./0123456789:;<=>?abcdefghijklmnopqrstuvwxyz[]^_{~}'
 3 | 
 4 |   -- generate char-to-num map.
 5 |   local charset = {}
 6 |   for i=1,#chars do
 7 |     charset[sub(chars,i,i)] = i
 8 |   end
 9 | 
10 |   local start  = 0x5f80
11 |   local offset = 0
12 | 
13 |   local function check()
14 |     if start+offset > 0x5fff then assert(false, 'event is too large.') end
15 |   end
16 | 
17 |   local function write_char(ch)
18 |     check()
19 |     poke(start+offset, charset[ch])
20 |     offset += 1
21 |   end
22 | 
23 |   local function write_bool(b)
24 |     check()
25 |     poke(start+offset, b and 1 or 0)
26 |     offset += 1
27 |   end
28 | 
29 |   local function write_uint8(n)
30 |     check()
31 |     poke(start+offset, n)
32 |     offset += 1
33 |   end
34 | 
35 |   local function flush()
36 |     check()
37 |     poke(start+offset, 255)
38 |     offset = 0
39 |   end
40 | 
41 |   local function write_str(s)
42 |     write_uint8(#s)
43 |     for i=1,#s do write_char(sub(s,i,i)) end
44 |   end
45 | 
46 |   function track(event, properties)
47 |     write_str(event)
48 |     if properties == nil then
49 |       flush()
50 |       return
51 |     end
52 |     for k,v in pairs(properties) do
53 |       write_str(k)
54 |       if type(v) == 'boolean' then
55 |         write_uint8(0)
56 |         write_bool(v)
57 |       elseif type(v) == 'number' then
58 |         write_uint8(1)
59 |         write_str(tostr(v))
60 |       elseif type(v) == 'string' then
61 |         write_uint8(2)
62 |         write_str(v)
63 |       else
64 |         assert(false, k .. ' must be a primitive.')
65 |       end
66 |     end
67 |     flush()
68 |   end
69 | end
70 | 
71 | --[[
72 | 
73 |   example:
74 | 
75 |     track('level completed', {
76 |       level = 4,
77 |       score = 9000,
78 |       found_secret = true,
79 |     })
80 | 
81 | --]]
82 | 


--------------------------------------------------------------------------------
/track_test.html:
--------------------------------------------------------------------------------
  1 | <html>
  2 |     <head>
  3 |         <meta charset="utf-8">
  4 |         <meta http-equiv="X-UA-Compatible" content="IE=edge">
  5 |         <title>PICO-8 Cartridge</title>
  6 |         <meta name="description" content="">
  7 | 
  8 | <STYLE TYPE="text/css">
  9 | <!--
 10 | 
 11 | canvas#canvas { width: 512px; height: 512px; }
 12 | 
 13 | .pico8_el {
 14 | 	float:left;
 15 | 	width:92px;
 16 | 	display:inline-block; 
 17 |   	margin: 1px;
 18 | 	padding: 4px;
 19 | 	text-align: center;
 20 | 	color:#fff;
 21 | 	background-color:#777;
 22 | 	font-family : verdana;
 23 | 	font-size: 9pt;
 24 | 	cursor: pointer;
 25 | 	cursor: hand;
 26 | }
 27 | .pico8_el a{
 28 | 	text-decoration: none;
 29 | 	color:#fff;
 30 | }
 31 | 
 32 | .pico8_el:hover{
 33 | 	background-color:#aaa;
 34 | }
 35 | 
 36 | .pico8_el:link{
 37 | 	background-color:#aaa;
 38 | }
 39 | 
 40 | canvas{
 41 |     image-rendering: optimizeSpeed;
 42 |     image-rendering: -moz-crisp-edges;
 43 |     image-rendering: -webkit-optimize-contrast;
 44 |     image-rendering: optimize-contrast;
 45 |     image-rendering: pixelated;
 46 |     -ms-interpolation-mode: nearest-neighbor;
 47 |     border: 0px
 48 | }
 49 | 
 50 | -->
 51 | </STYLE>
 52 |     
 53 | </head>
 54 | 
 55 | <body bgcolor=#303030>
 56 | 
 57 | 	<br><br><br>
 58 | 
 59 | 	<center><div style="width:512px;">
 60 | 
 61 | 	<canvas class="emscripten" id="canvas" oncontextmenu="event.preventDefault()"></canvas>
 62 | 
 63 | 	<script type="text/javascript">
 64 | 		var canvas = document.getElementById("canvas");
 65 | 		canvas.width = window.innerWidth;
 66 | 		canvas.height = window.innerHeight;
 67 | 
 68 | 		// show Emscripten environment where the canvas is
 69 | 		// arguments are passed to PICO-8
 70 | 		
 71 | 		var Module = {};
 72 | 		Module.canvas = canvas;
 73 | 		
 74 | 		/*
 75 | 			// When pico8_buttons is defined, PICO-8 takes each int to be a live bitfield
 76 | 			// representing the state of each player's buttons
 77 | 			
 78 | 			var pico8_buttons = [0, 0, 0, 0, 0, 0, 0, 0]; // max 8 players
 79 | 			pico8_buttons[0] = 2 | 16; // example: player 0, RIGHT and Z held down
 80 | 			
 81 | 			// when pico8_gpio is defined, reading and writing to gpio pins will
 82 | 			// read and write to these values
 83 | 			var pico8_gpio = new Array(128);
 84 | 		*/
 85 | 	</script>
 86 |   <script>
 87 | ;(function() {
 88 |   var index = 0
 89 |   var chars = ' !"#%\'()*+,-./0123456789:;<=>?abcdefghijklmnopqrstuvwxyz[]^_{~}'
 90 |   function readByte(arr) {
 91 |     var b = arr[index]
 92 |     index++
 93 |     return b
 94 |   }
 95 |   function readChar(arr) {
 96 |     var charCode = arr[index]
 97 |     index++
 98 |     return chars[charCode-1]
 99 |   }
100 |   function readString(arr) {
101 |     var strlen = readByte(arr)
102 |     var str = ''
103 |     for (var i = 0; i < strlen; i++) str += readChar(arr)
104 |     return str
105 |   }
106 |   function readNum(arr) {
107 |     var numStr = readString(arr)
108 |     return parseInt(numStr, 10)
109 |   }
110 |   function readBool(arr) {
111 |     return readByte(arr) > 0
112 |   }
113 |   function readValue(arr) {
114 |     var type = readByte(arr)
115 |     if (type === 0) return readBool(arr)
116 |     if (type === 1) return readNum(arr)
117 |     if (type === 2) return readString(arr)
118 |     throw new Error('Failed read.')
119 |   }
120 |   function onTrack(o, onTrack) {
121 |     return new Proxy(o, {
122 |       set: function(target, property, value) {
123 |         if (value === 255) {
124 |           // Find "end-of-track" index.
125 |           var End = Number(property)
126 |           // Read event name.
127 |           var event = readString(target)
128 |           // Read properties.
129 |           var properties = {}
130 |           while (index < End) {
131 |             var key = readString(target)
132 |             var value = readValue(target)
133 |             properties[key] = value
134 |           }
135 |           // Reset offset.
136 |           index = 0
137 |           // Call onTrack handler.
138 |           onTrack(event, properties)
139 |         }
140 |         target[property] = value
141 |         return true
142 |       },
143 |     })
144 |   }
145 |   pico8_gpio = onTrack(new Array(128), function(event, properties) {
146 | analytics.track(event, properties)
147 |   })
148 | })()
149 |   </script>
150 | <script>
151 |   !function(){var analytics=window.analytics=window.analytics||[];if(!analytics.initialize)if(analytics.invoked)window.console&&console.error&&console.error("Segment snippet included twice.");else{analytics.invoked=!0;analytics.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","debug","page","once","off","on"];analytics.factory=function(t){return function(){var e=Array.prototype.slice.call(arguments);e.unshift(t);analytics.push(e);return analytics}};for(var t=0;t<analytics.methods.length;t++){var e=analytics.methods[t];analytics[e]=analytics.factory(e)}analytics.load=function(t,e){var n=document.createElement("script");n.type="text/javascript";n.async=!0;n.src="https://cdn.segment.com/analytics.js/v1/"+t+"/analytics.min.js";var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(n,a);analytics._loadOptions=e};analytics.SNIPPET_VERSION="4.1.0";
152 |   analytics.load("Qvgu5SMxYELpqRnwSedmpnvL6OLzcJvA");
153 |   analytics.page();
154 |   }}();
155 | </script>
156 | 
157 | 	<script async type="text/javascript" src="track_test.js"></script>
158 | 	  
159 | 	<script>
160 | 		// key blocker. prevent cursor keys from scrolling page while playing cart.
161 | 		
162 | 		function onKeyDown_blocker(event) {
163 | 			event = event || window.event;
164 | 			var o = document.activeElement;
165 | 			if (!o || o == document.body || o.tagName == "canvas")
166 | 			{
167 | 				if ([32, 37, 38, 39, 40].indexOf(event.keyCode) > -1)
168 | 				{
169 | 					if (event.preventDefault) event.preventDefault();
170 | 				}
171 | 			}
172 | 		}
173 | 
174 | 		document.addEventListener('keydown', onKeyDown_blocker, false);
175 | 
176 | 	</script>
177 |         
178 | 	<br>
179 | 
180 | 	<div class=pico8_el onclick="Module.pico8Reset();">
181 | 
182 | 	<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAaklEQVR4Ae2dOwoAMQhE15A+rfc/3bZ7AlMnQfywCkKsfcgMM9ZP+QHtIn0vLeBAFduiFdQ/0DmvtR5LXJ6CPSXe2ZXcFNlTxFbemKrbZPs35XogeS9xeQr+anT6LzoOwEDwZJ7jwhXUnwkTTiDQ2Ja34AAAABB0RVh0TG9kZVBORwAyMDExMDIyMeNZtsEAAAAASUVORK5CYII=" alt="Reset" width=12 height=	12/>
183 | 
184 | 	Reset</div>
185 | 
186 | 	<div class=pico8_el onclick="Module.pico8TogglePaused();">
187 | 
188 | 	<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAPUlEQVR4Ae3doQ0AIAxEUWABLPtPh2WCq26DwFSU/JPNT166QSu/Hg86W9dwLte+diP7AwAAAAAAgD+A+jM2ZAgo84I0PgAAABB0RVh0TG9kZVBORwAyMDExMDIyMeNZtsEAAAAASUVORK5CYII=" alt="Pause" width=12 height=12/>
189 | 
190 | 	Pause</div>
191 | 	<div class=pico8_el onclick="Module.requestFullScreen(true, false);">
192 | 	<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAaklEQVR4Ae2dsQ1AIQhExfze1v2ns3UCrfgFhmgUUAoGgHscp21wX9BqaZoDojbB96OkDJKNcTN2BHTyYNYmoT2BlPL7BKgcPfHjAVXKKadkHOn9K1r16N0czN6a95N8mnA7Aq2fTZ3Af3UKmCSMazL8HwAAABB0RVh0TG9kZVBORwAyMDExMDIyMeNZtsEAAAAASUVORK5CYII=" alt="Fullscreen" width=12 height=12/>
193 | 
194 | 	Fullscreen</div>
195 | 	<div class=pico8_el onclick="Module.pico8ToggleSound();">
196 | 	<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAXklEQVR4Ae2doQ4AIQxD4YLH8v9fh+ULhjpxxSwLg2uyapr1JRu1iV5Z+1BGl4+xNpX38SYo2uRvYiT5LwEmt+ocgXVLrhPEgBiw8Q5w7/kueSkK+D2tJO4E/I3GrwkqQCBabEj/4QAAABB0RVh0TG9kZVBORwAyMDExMDIyMeNZtsEAAAAASUVORK5CYII=" alt="Toggle Sound" width=12 height=12/>
197 | 	
198 | 	Sound</div>
199 | 	<div class=pico8_el ><a target="_new" href="http://www.lexaloffle.com/bbs/?cat=7&sub=2">
200 | 	<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAlElEQVR4Ae2dMQ5FQBCGh6jcwAkkateg3DiAa+iQUGqVKi95FQfAJRQOoHeBUf8JyQqKjZ1uMzuz2e/LTE3KhyF7kSlgLOykas23f6D+A9Yp84aAOYU15pcJnfji0Il2ID8HzC4y38ZrnfIBGxeRoR3c3EWrACdsV5BOsx7OSRnrOXh4F5HzA6bevwUn8wlz7eCDsQM99B3ks0s/4QAAABB0RVh0TG9kZVBORwAyMDExMDIyMeNZtsEAAAAASUVORK5CYII=" alt="More Carts" width=12 height=12/>
201 | 
202 | 	Carts</a></div>
203 | 
204 | 	<br>	
205 | 
206 | 	</div></center>
207 | 	<br><br>
208 | 
209 | </body></html>
210 | 
211 | 
212 | 


--------------------------------------------------------------------------------