{"id":26716413,"url":"https://github.com/processing/p5.js-compatibility","last_synced_at":"2025-04-14T01:25:15.040Z","repository":{"id":273622080,"uuid":"920321197","full_name":"processing/p5.js-compatibility","owner":"processing","description":"Add-on libraries that add p5.js 1.x features to p5.js 2.x for backwards compatibility","archived":false,"fork":false,"pushed_at":"2025-04-13T17:03:57.000Z","size":50,"stargazers_count":1,"open_issues_count":2,"forks_count":2,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-13T18:20:48.139Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/processing.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-22T00:08:12.000Z","updated_at":"2025-04-13T17:03:58.000Z","dependencies_parsed_at":"2025-03-13T13:25:09.805Z","dependency_job_id":"592c942b-627c-41e4-a4c2-ff749f714d04","html_url":"https://github.com/processing/p5.js-compatibility","commit_stats":null,"previous_names":["processing/p5.js-compatibility"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/processing%2Fp5.js-compatibility","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/processing%2Fp5.js-compatibility/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/processing%2Fp5.js-compatibility/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/processing%2Fp5.js-compatibility/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/processing","download_url":"https://codeload.github.com/processing/p5.js-compatibility/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248759421,"owners_count":21157158,"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":[],"created_at":"2025-03-27T15:27:05.552Z","updated_at":"2025-04-14T01:25:15.017Z","avatar_url":"https://github.com/processing.png","language":"JavaScript","readme":"# p5.js-compatibility\n\nEven as p5.js 2.0 becomes more stable, p5.js 1.x will continue to be supported until August, 2026. Between 1.x and 2.0, there are many additions, and some breaking changes. In addition to making p5.js 2.0 available as a library, we are working on preparing several compatibility add-on libraries that would make it possible to keep using 1.x features that are no longer part of 2.0.\n\nWe are working on three compatibility add-on libraries which will make these 1.x features available for 2.0:\n\n1. [preload.js](https://github.com/processing/p5.js-compatibility/blob/main/src/preload.js)\n\n2. [shapes.js](https://github.com/processing/p5.js-compatibility/blob/main/src/shapes.js)\n\n3. [data.js](https://github.com/processing/p5.js-compatibility/blob/main/src/data.js)\n\nYour feedback is welcome [on this issue](https://github.com/processing/p5.js/issues/7488)!\n\n# How to update p5.js code from 1.x to 2.0\n\nMost things are the same between p5.js 1.x and 2.0, but there are some big differences: p5.js 2.0 has new capabilities, and it also no longer supports some aspects of p5.js 1.x.\n\n## Do I have to update my 1.x sketches?\n\nFirst, you should try to update the version and see if the sketch still runs! In many cases, no actions are needed - just update the version and you’re all set.\n\nHowever, if the sketch doesn’t run anymore using 2.0, then you can either update it to use 2.0, or keep it using 1.x. If any of this sounds applicable, then follow the guide below to update your sketches:\n\n* If you want to use p5.js 2.0 features, like variable-weight fonts\n* If you need your sketches to work after August, 2026. At that point, 1.x will no longer be supported, and 2.0 will become the default in the p5.js Editor. If you face any challenges in making updates, please consider [joining the discussion](https://github.com/processing/p5.js/issues/7488) and [filing bugs](https://github.com/processing/p5.js/issues) to help make p5.js 2.0 a robust tool for the whole community.\n* If you want to use an add-on library or community library that uses p5.js 2.0 features\n* If you want to be able to better integrate with other tools and libraries in the JavaScript ecosystem\n\n## How can I update my 1.x sketches?\n\nStep 1: Switch to 2.0 by using one of the [beta releases](https://github.com/processing/p5.js/releases/) when you import the core library! An [option to switch to 2.0 will be available in the p.js Editor](https://github.com/processing/p5.js-web-editor/pull/3334) once the new release is live!\n\nStep 2: Try running your sketch! In many cases, this will work right away, and no other changes would be needed.\n\nStep 3: If your 1.x sketch does not run with p5.js 2.0, you have two options:\n\n* Update your code to match 2.0\n* or include a compatibility add-on library ([this will also be possible in the p.js Editor](https://github.com/processing/p5.js-web-editor/pull/3334) once the new release is live.\n\n# Changes to make if your sketch includes…\n\n## …loading images, sound, fonts, and other assets\n\nOne of the biggest changes in 2.0 is involves how you can include other files, media, and assets. The p5.js 1.x style of using `preload()` does not reflect anymore how assets are loaded on the web, so p5.js 2.0 uses JavaScript’s async/await keywords to support asynchronicity.\n\nIf you’re interested in the history of async [read on here](https://dev.to/limzykenneth/asynchronous-p5js-20-458f)!\n\nTo play around, check out [the example from the p5.js 1.x `preload()` reference](https://p5js.org/reference/p5/preload/), but get a very big file instead of bricks.jpg.\n\n\n\n\u003ctable\u003e\n\u003ctr\u003e\u003cth\u003ep5.js 1.x\u003c/th\u003e\u003cth\u003ep5.js 2.x\u003c/th\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eBlank “Loading…” screen, then image shown\u003c/td\u003e\u003ctd\u003eRed background while image loads\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\n\n```js\nlet img;\n\nfunction preload() {\n  img = loadImage('bricks.jpg');\n}\n\nfunction setup() {\n  createCanvas(100, 100);\n\n  // Red backgorund is ignored\n  background(255, 0, 0);\n\n  // Draw the image.\n  image(img, 0, 0);\n\n  describe('A red brick wall.');\n}\n```\n\n\u003c/td\u003e\u003ctd\u003e\n\n```js\nlet img;\n\nasync function setup() {\n  createCanvas(100, 100);\n\n  // Red background while asset loads\n  background(255, 0, 0);\n\n  // Wait for the image to load\n  img = await loadImage('bricks.jpg');\n\n  // Draw the image.\n  image(img, 0, 0);\n\n  describe('A red brick wall.');\n}\n```\n\n\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\nIf it takes a while to load the image, the sketch will be \"paused\" on the line `img = await loadImage('/assets/bricks.jpg');` - once the image is loaded, it will resume.\n\n\n## …using registerPreloadMethod in an add-on libraries\n\nUnder to hood, returns a **Promise** from each loadImage, loadSound, and similar functions. Promises are widely used in JavaScript, so it is possible to use a callback in p5.js 1.x to create a Promise, but p5.js 1.x doesn't expect promises to be used, so you have to ensure yourself that, for example, your draw function doesn't start running before loading is done. For an example of a Promise using a callback, check out the example below that makes p5.sound.js compatible with both 1.x and 2.0:\n\nIf your add-on library built with p5.js 1.x uses `registerPreloadMethod` such as in this example from [p5.sound.js](https://github.com/processing/p5.sound.js):\n\n```js\np5.prototype.registerPreloadMethod('loadSound', p5.prototype);\n```\n\nThen to make your add-on library compatible with **both p5.js 1.x *(preload)* and p5.js 2.0 *(promises)***, this this line can be removed (the method `loadSound`, in this example, does not need to be registered) and the method can be updated as follows:\n\n```js\nfunction loadSound (path) {\n   if(self._incrementPreload \u0026\u0026 self._decrementPreload){\n     // tTis is the check to determine if preload() is being used, as with\n     // p5.js 1.x or with the preload compatibility add-on library. The function\n     // returns the soundfile.\n \n     self._incrementPreload();\n \n     let player = new p5.SoundFile(\n       path,\n       function () {\n         // The callback indicates to preload() that the file is done loading\n         self._decrementPreload();\n       }\n     );\n     return player;\n \n   }else{\n     // Otherwise, async/await is being used, so the function returns a promise,\n     // which loads the soundfile asynchronously.\n\n     return new Promise((resolve) =\u003e {\n       let player = new p5.SoundFile(\n         path,\n         function () {\n           // The callback resolves the promise when the file is done loading\n           resolve(player);\n         }\n       );\n     });\n   }\n }\n```\n\nAnd that's it! You can check this example of making an add-on library backwards-compatible and work with p5.js 2.0 here: [the p5.sound.js example](https://github.com/processing/p5.sound.js/commit/608ffa93f241538c4fb353544f6d01275911d212)\n\n## …making shapes\n\nIf you use `vertex` and `bezierVertex` is the p5.js 1.x code, here's how you can approach updating your code.\n\nThe below code is based on the [custom shapes](https://p5js.org/tutorials/custom-shapes-and-smooth-curves/) tutorial:\n\n```js\nfunction setup() {\n  createCanvas(windowWidth, windowHeight);\n  background(100);\n}\nfunction draw() {\n  translate(width/2, height/2);\n  \n  // Draw the curved star shape - use one of the snippets below, depending on p5.js version\n\n  describe(\"A white star on a gray background in the middle of the canvas\")\n}\n```\n\n\u003ctable\u003e\n\u003ctr\u003e\u003cth\u003ep5.js 1.x\u003c/th\u003e\u003cth\u003ep5.js 2.x\u003c/th\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\n\n```js\n// Draw the curved star shape.\nbeginShape();\n\n// Original anchor at top.\nvertex(0, -100);\n\n// Top-right curve.\nbezierVertex(0, -50, 50, 0, 100, 0);\n\n// Bottom-right curve.\nbezierVertex(50, 0, 0, 50, 0, 100);\n\n// Bottom-left curve.\nbezierVertex(0, 50, -50, 0, -100, 0);\n\n// Top-left curve.\nbezierVertex(-50, 0, 0,-50, 0,-100);\nendShape();\n```\n\n\u003c/td\u003e\u003ctd\u003e\n\n\n```js\n// Draw the curved star shape.\nbeginShape();\nbezierOrder(3);\n\n// Original anchor at top.\nbezierVertex(0, -100);\n\n// Top-right curve.\nbezierVertex(0, -50);\nbezierVertex(50, 0);\nbezierVertex(100, 0);\n\n// Bottom-right curve.\nbezierVertex(50, 0);\nbezierVertex(0, 50);\nbezierVertex(0, 100);\n\n// Bottom-left curve.\nbezierVertex(0, 50);\nbezierVertex(-50, 0);\nbezierVertex(-100, 0);\n\n// Top-left curve.\nbezierVertex(-50, 0);\nbezierVertex(0, -50);\nbezierVertex(0,-100);\n\nendShape();\n```\n\n\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\nThe [custom shapes tutorial](https://p5js.org/tutorials/custom-shapes-and-smooth-curves/) has a bit more detail on this, but Bézier curves need multiple points. In p5.js 1.x, they use three control points. In p5.js 2.0, that number is set by `bezierOrder`. Then, in p5.js 1.x each `bezierVertex(...)` was actually a set of three points describing a smooth curve. In p5.js 2.0, each `bezierVertext(x, y)` is just one point; you need the first point to anchor, and each curve after that needs 3 points.\n\n## …using non-JavaScript data structures and functions\n\nOne bit change relates to data structures in JavaScript. The following funcitons have been removed in p5.js 2.0. These were originally in p5.js 1.x because, historically, they were also in Processing. However, p5.js is a JavaScript library, and JavaScript objects and key-value maps can be used instead of these functions:\n\n* `createStringDict()`\n* `createNumberDict()`\n* `p5.TypedDict`\n* `p5.NumberDict`\n\nInstead of the above functions, we would recommend using [built-in JavaScript Objects](https://p5js.org/reference/p5/Object/ )\n\nThe below functions are also better supported in JavaScript itself:\n\n* `append()`\n* `arrayCopy()`\n* `concat()`\n* `reverse()`\n* `shorten()`\n* `sort()`\n* `splice()`\n* `subset()`\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprocessing%2Fp5.js-compatibility","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprocessing%2Fp5.js-compatibility","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprocessing%2Fp5.js-compatibility/lists"}