Overly Complex Examples May be Inhibiting Uptake

[Coronavitae]

PDPortal has been live for well over a year, and as far as I can tell from multiple google searches, no games (not even minor hobby projects) have made use of it. Why is that?

It isn't the tech. Net-Tac-Toe shows it works amazing, and very fast.
It isn't the website. It's well-designed, minimalist for users, and easy for devs.
The lack of developer access to two playdates probably contributes, but the dev tools on the website help address this.

I think it's the complexity of the examples. My knowledge of Lua and coding conventions is not sufficient to say PDPortal is "insufficiently documented," but I can say that it is harder to implement than it needs to be. I don't think this is an issue with PDPortal.lua. I think it is an issue with the examples.

As far as I have understood the code, the vast majority of the complex back-end work is handled beautifully by the website and PDPortal.lua. It should therefore be easy for any Joe Shmoe to quickly mock up a simple "Hello World!" app, link to a friend over PDPortal.net, and see the portal in action.

It is not.

Every example is coded in a way that is significantly more complex than, say, the examples bundled with the PlaydateSDK. I can see (after over an hour of review and cross-referencing) that these are actually very elegant implementations of the examples; they are not poorly coded in any way. However, they do not make it easy to quickly understand and copy their methods.

Take the update loop from the very first example, for instance:

class('Example01SimplePortal').extends(PdPortal)
local Example01SimplePortal <const> = Example01SimplePortal

playdate.display.setRefreshRate(50)

function Example01SimplePortal:init()
	-- If your subclass overrides the init method, make sure to call super!
	Example01SimplePortal.super.init(self)

	self.connected = false
	self.peerId = nil
	self.updatingPeer = false
end

local portalInstance = Example01SimplePortal()

playdate.update = function()
	-- Required for serial keepalive
	portalInstance:update()
end

Once I understood it, I could see that this is a cool way to structure a program, and I may imitate it in the future. However, even the question "what do I need to put into my update loop?" is obscured by the use of portalInstance:update() and the creation of the Example01SimplePortal class. Every example has elevated degrees of complexity in similar ways.

I think there should be simpler examples that do much less complex things. For example, a simple "hello world" app that:
(1) visually shows the user the connection status (using simple coding such as drawText(connection_status, x, y))
(2) instructs the user to press a to connect (using onButtonPress)
(3) lets the user press b to send "hello world" in one of several languages selected by crank
(4) displays any hello-world string received from the other end (again using a simple drawText

My proposal is for me to make a few apps of this kind over the next few weeks, aiming for a similar level of complexity to the example apps provided with the PlaydateSDK.