What if instead of directing random strangers on the internet to your boring personal website, you could direct them to an entire OS - where through exploring, they get to know you?


![Capybara OS demo](https://cloud-ir4w2s05f-hack-club-bot.vercel.app/0screenrecording.gif)
[Live Demo ](https://ecd6d5e2-03cd-4131-ac4a-9e4cf22bb73b-00-28qahbc8n17eh.worf.replit.dev/) & 
[Sample Code](https://replit.com/@ThomasStubblef2/Step8#index.html)  

  *(P.S. This is a sample of what your OS might look like at the end of the entire batch, except HA NO it's going to be about you and fit your vibe so not look/feel like this at all. Yours will also have a totally different set of apps by the end of the batch.)*

The Operating System (OS) will be entirely web-based (using HTML, CSS, and JS). An Operating System is the interface & set of logic you use to interact with applications. You'll be the designer and developer of your OS (so you'll have complete creative freedom). You'll decide the content, style, features, etc. If your website looks totally different from mine by the end of the batch jam, then you've done the Jam well. If it looks the same, go back to the drawing board. Your Personal Operating System will be a website you can share with people (friends, club members, people you meet at hackathons, etc) to allow them to easily get a sense of who you are and the type of things you like to do.

**Today you'll be creating an awesome welcome screen for your personalOS. It will be plenty of fun and you'll have an awesome-looking one-of-a-kind product that you'll build upon in subsequent Jams.**

![this is what today's build may look like](https://cloud-nzaoewszc-hack-club-bot.vercel.app/0screenshot_2023-07-23_at_2.31.58_pm.png)

There are six steps/headings in this Jam! Go through each and begin building your personalOS.

**Outline:**
1. **Enter The Code Editor** *(start coding in your browser)*
2. **Build with Elements** *(create elements for your welcome screen)*
3. **Personalize Your Content** *(make the content personally relevant to you)*
4. **Style Your Elements** *(make your elements fit your aesthetic)*
6. **Next Time on Building Your Personal OS**
  
## Enter the Code Editor
Hey there Hacker! Let's get you setup

### Create an Account
Head over to the [Replit Website](https://replit.com/languages/html) and create an account

<Dropdown title="What is Replit?">
Replit is a web-based independent development environment (IDE). Basically, Replit allows you to write code in your browser and instantly deploy your site to the entire world. I suppose you could say it's *magical*. 
</Dropdown>



<Dropdown title="If you're unable to use Replit or would rather not use Replit">
If for whatever reason you have difficulty accessing Replit, visit <a href="https://firewalledreplit.com/">Firewalled Replit</a>.
I also recommend checking out GitHub code spaces or running a local development environment in VS Code.
All the code is the same regardless of the code editor you use.😉
</Dropdown>



### 2. Create a new Repl/Project
Welcome to your Replit Dashboard! Once inside, tap Create a Repl and then select **HTML, CSS, and Javascript** as your template. 

Replit will kindly start you off with some boilerplate code (starter code). 

![Replit-Signup](https://cloud-c6z75ah46-hack-club-bot.vercel.app/0export_jun_15_2023_0159_pm.gif)


## Build with Elements

### What are elements?
Every site you've ever visited has elements. Elements are the building blocks that come together to create websites. For example, this block of text is an element. The gif you'll see below is also an element. Even the container that holds the text you are reading is an element. Try right-clicking this site and tapping Inspect, you'll see a bunch of elements. HTML is the file format for these elements.

![Inspect Screen](https://cloud-8ywcul7zm-hack-club-bot.vercel.app/0inspect.gif)

#### What makes an element?
Elements consist of three parts. 

Elements consist of an opening tag, the content in the middle, and a closing tag. So for example `<p>Sample Content</p>` creates paragraph text because there is an opening tag (`<p>`), with content in the middle (`Sample Content`), and a closing tag (`</p>`) indicating where the content ends 

![bagel](https://cloud-rd8lvcrjx-hack-club-bot.vercel.app/0video.gif)
*(bagels are a lot like tags or I suppose you could say tags are a lot like bagels... depending on your perspective)*

### Where can I place them?

Let's begin by deleting all the starter code that Replit gave you.

![delete starter code](https://cloud-884himjr3-hack-club-bot.vercel.app/0nameswitch.gif)

Orpheus the Dinosaur *(don't ask who [Orpheus](https://workshops.hackclub.com/orpheus/) is)* asks that you please copy and paste the code below into your project

```
<!DOCTYPE html>
<html>

  <body>
  
  </body>

</html>
```

The body of your site is contained inside of an opening tag (`<body>`) and a closing tag (`</body>`). The content of your site goes inside the body.  **Inside your body is where you'll place your elements.**

It's sort of like how cream cheese goes inside a bagel. A bagel has a top and bottom and all of the tasty cream cheese in the middle.

Let's fill your body tag sandwich with some tasty content! 🥯

### How can I make elements for my welcome screen?
Inside of your body tags, let's write some code

```
<body>
  <p>Hello world!</p>
</body>
```

You've created your first element & it's a `<p>` element (p stands for paragraph)! Congratulations!

Let's try making a heading! Simply create a new element with h1 tags.
```
<body>
  <h1>Welcome to my OS</h1>
  <p>Hello world!</p>
</body>
```

Awesome. We can also make smaller headings. `h1` is the largest heading, but you can also create an `h2`, `h3`, `h4`, & so on. 

```
<body>
  <h1>Welcome to my OS</h1>
  <h2>Introduction</h2>
  <p>Hello world!</p>
</body>
```

The text is neat, but let's add an image:
First, we need to drag an image into the Replit file manager.

![Drag & Drop](https://cloud-id4r1tr7g-hack-club-bot.vercel.app/0drag_drop.gif)

```
<body>
  <h1>Welcome to my OS</h1>
  <h2>Introduction</h2>
  <p>Hello world!</p>
  <img src="./nameOfImage.jpeg" />
</body>
```

You can also do a direct link to the image (as .png, .jpeg, etc at the end of the URL), so for example here's code for placing an image of a Capybara 

`<img src="./imageOfMe.png" />`

The image tag has a property of `src` which stands for source. You can pass in the direct link to the image or import an image and set the src as `"./imageName.png"`.

![Website with text on top and a Capybara image](https://cloud-33eico6lp-hack-club-bot.vercel.app/0screenshot_2023-06-16_at_11.54.32_am.png)

### Let's link to another page
HTML (HyperText Markup Language) was built for scientists to be able to share research documents (& is now used on every website on the internet). If you know anything about scientists, then you know they LOVE to reference other pages. 

For this reason, HTML makes it easy for you to hyperlink to other pages.

```
<body>
  (rest of your content)
  <a href="https://example.com/">label</a>
</body>
```

Replace the label with the label of the button (so for example [Instagram](https://www.instagram.com/starthackclub/)) and link with the URL (like https://www.instagram.com/starthackclub/).

You can use this to link to a personal social media, a GitHub, a random website about your favorite creature, or just not make a tag at the moment. It's totally up to you. 

## Personalize Your Content
Soo... surprise, you didn't realize but you just started your onboarding screen for your operating system.

**Go ahead and fill it up with your content.** 

Don't know what to add? Perhaps try:
* Linking to your favorite playlist
* Adding a picture of a pet
* Writing a bit about your favorite hobbies
* etc

### Customize the text content and image
Make the text content whatever you would like users to see when they first land on your site. Be creative and have fun with it! 

Select an image for your site that represents you (either literally like a selfie or metaphorically like your favorite creature) by changing the src of the image to a URL or path to your image. 

### Additional Challenge 
Discover some unique tags on the [W3 Tags Site](https://www.w3schools.com/TAGS/default.asp). There are 100+  tags for you to experiment with. Go dive into the W3 Tags Directory and find some random tags and experiment with them on your site. Have fun :) 

here are some tags we really like:
* `<s>Strike Through</s>`
* `<p>break the </br> line like this</p>`
* `<p>use strong to <strong>bold text</strong></p>`
* `<p> <dfn>DFN Tag</dfn> is a tag that marks something being defined</p>`
* `<p><abbr title="abbreviation">abbr</abbr> is a tag that marks an abbreviated term</p>`


### Content Complete
Okay, so you should now have the content for your "Welcome to My OS" screen and it should feel totally unique to you (i.e. if a friend saw your welcome screen, they would immediately know it was your OS).

Your content most likely looks rather bland and uninteresting which leads us into our next topic... styling our content!

![content styling in progress](https://cloud-9jc9u3xyy-hack-club-bot.vercel.app/0screenshot_2023-06-16_at_3.51.07_pm.png)

## Style Your Elements
### What's a style?
A style is a property-value pair that changes the way an element looks.

Styles can exist within an HTML file when written in-line, but can also be in a separate file (styles.css). For now, we're going to write the styles inside of our HTML file (inside of opening tags)

To apply a style, it's as simple as:
`<tag style="property: value"> content </tag>`

**Every style has a property and a value.** 
For example, a style may be color with the value of red (to turn the text red)

### Styling Color 🎨
To change the color text you would simply write
`<p style="color: red">This text is red</p>`

You can also add a background color: 
```
<body style="background-color: #c9ffcf">
  // your content//
</body>
```

Easy, right? 

*p.s. you'll notice I used hex (#c9ffcf) instead of the name of a color (red) for the second example. Hex is a format for representing color. You can use either the name of a color or the hex value. To find hex values, try googling "hex color picker"

### Styling Shape & Size
Images can have styles too!

Your image is probably very large. Let's change the size & shape.


**IF YOUR IMAGE IS TOO LARGE OR TOO SMALL, BE SURE TO ADJUST THE HEIGHT AND WIDTH AS IS DONE BELOW** 

Simply go to the image and apply a style property that sets the width and height: 

`<img style="width: 64px; height: 64px" src="https://cloud-pc8imajxj-hack-club-bot.vercel.app/1img_1181.jpg" />`

I chose to make the width and height 64px, but you don't have to! Pick your own size, play with it, and have fun!

*Note: Semicolons are used to separate CSS properties*

##### *\*Crunch*\*
Your image might be a bit crunched up. Try to Google how to fix this (maybe even ask GPT). Even a very basic search term such as What is the CSS Property for making an image not crunch, would probably work.

![crunched image](https://cloud-4cdvjzqmo-hack-club-bot.vercel.app/0screenshot_2023-06-16_at_12.43.50_pm.png)

<Dropdown title="Solution">
  Upon scrubbing through the results, I found the `object-fit: cover` property. Let's try applying that to our image. Ah lovely, and just like that our image is uncrunched. Whenever you run into something that looks ugly and you want to make it look beautiful, just google it and Google will help you out.
</Dropdown>


##### *\*Rounddddd*\*
Optionally, you can round your corners. Try googling this! (maybe you can even turn your image into a circle shape if you'd like)

<Dropdown title="Solution">
You probably found a nifty little CSS property called border-radius. 
simply write style="border-radius: 16px; object-fit: cover" on your image tag.
Note: Semicolons are used to separate CSS properties
</Dropdown>


![rounded image](https://cloud-b43epg4q2-hack-club-bot.vercel.app/0screenshot_2023-06-16_at_3.59.41_pm.png)

### Styling Font
Adding a font in CSS is easy!

The easiest way to add a font is to visit the [W3 Library of browser-built-in fonts](https://www.w3.org/Style/Examples/007/fonts.en.html) and select one that fits the vibe of your site! 

Once you pick out your favorite font(s), go to the body and put a style property of font-family on the opening tag.

`<body style="font-family: Helvetica, Noto Sans, sans-serif">`

*Note: If you want cooler fonts, checkout [Google Fonts](https://fonts.google.com/) and [this document for learning how to integrate a Google font into your project](https://developers.google.com/fonts/docs/getting_started).*  *You'll need to put a link inside `head` tags (which includes content that is not visible on the site, but that the browser uses to configure the site)*

*Additional Note: not all computers have access to the same fonts, so if a computer does not have access to a font, it will go to the next one in the list. For this reason, I suggest putting selecting your favorite three fonts and putting them in order from most-liked to least-liked.*

*Final Note: you can use the font-size property and font-weight property to further change the visual appearance of a text element*  

### Styling Space ✨
Space is created by a combination of Margin (not margarine, MARGIN) and padding (fluff).

Margin is the space between your picture frames on your wall. 

Padding is the gap between the photo and the frame. If you had a box with an item in the middle, the space between the object in the center and the walls of the box is padding. 

Also... here's a comedy skit by Shubham at Epoch Bay Area to learn about Margin and Padding

<video src="https://cloud-2jto14u7d-hack-club-bot.vercel.app/0vid_20221230_184903086.mp4" controls="controls" style={{maxWidth: "480px"}}>
</video>

We'll get more into this later, but right now I would just like to bring our items closer together. 

![spaced out](https://cloud-5txt6wpqn-hack-club-bot.vercel.app/0screenshot_2023-06-16_at_4.12.11_pm.png)

So if we open the inspect window...

![Margin is the problem](https://cloud-p8iio5lh4-hack-club-bot.vercel.app/0screenshot_2023-06-16_at_4.19.38_pm.png)

We can see that the default margin on the h1 is quite large and it's making the site look a bit awkward. Let's correct that. 

Let's reduce the margin on the h1 tag

` <h1 style="margin: 4px;">thomasOS</h1>`

*Note: px stands for pixels, so we now have a 4px space on all sides for the header text element*

If you wanted to add some space within your heading, you could add padding, so perhaps make it
` <h1 style="padding: 4px; margin: 4px; background-color: #000; color: #fff">thomasOS</h1>`
(you can see the padding added a gap between the walls of the element and the content itself)

### Keep Hacking! 

Try adding the `background-color`, `color`, and `font-family` properties on your `body` tag to make your site look funky (or whatever style you're going for). Not sure how to use those styles? Google it!

This is what mine looked like after some tinkering. Go for whatever makes you smile! This was just my style at the moment of writing the Jam.
![what mine looked like](https://cloud-nzaoewszc-hack-club-bot.vercel.app/0screenshot_2023-07-23_at_2.31.58_pm.png)



*Note: with both padding and margin, you can change the spacing in a specific direction by appending -top, -bottom, -right, or -left. For example you could add margin-top: 4px; or padding-left: 16px;*

Alright, lovely! Here's my finished site for this episode of the batch. I hope your site looks nothing like this! Please take the opportunity to have fun with this site and do something wild!

![Finished Site](https://cloud-423oznftn-hack-club-bot.vercel.app/0screenshot_2023-06-16_at_4.27.35_pm.png)

*Note: You'll notice I added some unique-looking tags inside the paragraph text, YOU CAN DO THAT TOO BY CHECKING OUT THE SOMEWHAT OPTIONAL ADDITIONAL CHALLENGE BELOW.*


## Next time on building your own PersonalOS...
In the next episode, we will build the foundation of our OS by:
* Adding a wallpaper
* Creating Your Window
* Creating the top bar
* Tracking time with JS


In this Jam, you'll be creating an awesome welcome screen for your personalOS. It will be plenty of fun and you'll have an awesome-looking one-of-a-kind product that you'll build upon in subsequent Jams.


Build Your Welcome Screen

Mmm... Hacker, you are more brave than I thought. You're continuing on to the second Jam in the Batch. I commend your efforts.

Today we're going to be diving into JavaScript and combining it with the HTML & CSS we learned about last time. Don't worry, you'll probably survive. We'll dive into JavaScript at the end of this Jam. 

You'll be adding your outlining your window, creating your desktop, and adding a top bar.

![ending with](https://cloud-d6rlms9ox-hack-club-bot.vercel.app/0image.png)

While we will be writing JavaScript, all code will still remain in the HTML file *(until next time on WebOS Jams)*

**Outline:**
1. **Defining Our “Window”**
2. **Making Our Desktop** *(+ finding the coolest desktop images)*
3. **Topping off with a Top Bar** *(+ letting time tell)*

## Defining the "Window"
Alrighty, so you ended off last time with the start of your welcome screen. Hopefully, it looks nothing like mine. As a reminder, here's what mine looked like:

![Window where we left off](https://cloud-p1jqe7wd2-hack-club-bot.vercel.app/0screenshot_2023-06-21_at_1.24.32_pm.png)

### What is a window?
A window is a box that defines where an application on your user interface (UI) starts and ends. I suppose a div could be any shape (if you want your windows to be circles, go for it!). 

As web developers, we refer to groupings/boxes as divs. You can create divs inside of divs if, for example, you had a bento box, that box itself is a group and then each little section within that group is a group. 

The walls inside the box define where the content (tasty food) starts & ends & the walls along the edge of the box define where the box begins & ends. 

![Bento Box of Divs](https://cloud-e63a9spt4-hack-club-bot.vercel.app/0divbento.png)

### Why do we need a window?
Having multiple windows will allow you to make users feel in control of their experience (by choosing which windows to open and focus on and which to ignore) and provide a novel/fun experience.

We need to create a div to group together the content of your window to define where your window begins and where it ends. 

### Creating our Window
Let's group all of our content within a div tag. 

That should look something like...

```html
    <body>
        <div>
            (the content of your site)
        </div>
    </body>
```

Cool... well you're site hopefully looks the same & you may be thinking you did something wrong. 

![grouped in a div](https://cloud-czlk8j3wo-hack-club-bot.vercel.app/0screenshot_2023-06-21_at_1.57.38_pm.png)

Fear not, you're on the right path. The group has no style attributes that would make it visually distinct from the rest of the page **yet**.

### Outlining our Window
Alrighty, let's apply a style on our div (yeah... you can apply styles to divs)

```html
    <div style="border: solid;">
        (content)
    </div>
```

Simple! Now we can see that we outlined our content. 

![stroke added](https://cloud-cn54hr3si-hack-club-bot.vercel.app/0screenshot_2023-06-21_at_2.04.50_pm.png)

*Hey... wanna have some fun? Visit [this site of border styles](https://developer.mozilla.org/en-US/docs/Web/CSS/border) and try adding some cool border effects (+ also your own width and color)*

### Finding our Boundary
We can set the width and height of our box (div) using the style property. 

At the moment our box is taking up the width of the entire site!

Let's change it to a fixed width.

```html
    <div style="border: solid; width: 128px;">
        (content)
    </div>
```

I chose 128 pixels, but you choose whatever size you'd like. If you'd like to be REALLY NIFTY you can also do `<div style="width: fit-content">`
which will make the div fit the width of your content.

Also, remember how last time how we rounded the corners of our image using border-radius? Try rounding the corners of your div:

`<div style="border: solid; width: 128px; border-radius: 16px">`

I chose 16px, but you can also make it much rounder by increasing that number! Experiment with it!

![image of it without space](https://cloud-25a3olvni-hack-club-bot.vercel.app/0screenshot_2023-06-21_at_2.21.27_pm.png)

AHH THE TEXT IS VERY *CLAUSTROPHOBIC*. YOU PUT IT IN A BOX AND IT HAS NOOOO BREATHING ROOM!

ADD PADDING FASTTTT

```html
    <div style="padding: 16px; (additional styles)">
        (content)
    </div>
```

ah... that feels *much* better...

(p.s. don't do 16px padding, do what feels right to you)

### Placing our Window
We have a screen and we have an element (our window). We want to place our element on top of our window and specify where we want it to be on the screen.

Because our window is going to exist on top of our desktop we need to use position absolute (which means that the position will not be relative to other items, but rather relative to the screen).


You don't totally need to understand position absolute right now. As we go deeper into the batch, it will start to make more sense. 

```html
    <div style="position: absolute; (additional styles)">
        (content)
    </div>
```

Awesome and with the `position: absolute` property, we unlock four more properties (top, bottom, left, right). Each one defines the distance that our window will be from the edges of the screen.

![This is the screen](https://cloud-rn4u95i7l-hack-club-bot.vercel.app/0thisisthescreen.gif)

To place it in the center, we can simply write

```html
    <div style="position: absolute; top: 50%; left: 50%; (additional styles)">
        (content)
    </div>
```

Hmm.. well that doesn't look quite right. The reason why is that the top, left, bottom, and right properties define how far the top left corner of our window is from the walls of our browser. To fix this, let's adjust the window so that the center of the window is the point that we're positioning around by using the `transform: translate(-50%, -50%)` property. 

```html
    <div style="position: absolute; top: 50%; left: 50%; 
transform: translate(-50%, -50%); (additional styles)">
        (content)
    </div>
```

![Image centered correctly](https://cloud-d0am8h8gg-hack-club-bot.vercel.app/0screenshot_2023-06-21_at_2.42.10_pm.png)

Alrighty great this is looking lovely.

This may be a good time to take a stretch break. You've been doing a lot of coding & your site is looking beautiful!

![Break](https://cloud-5gpc0802p-hack-club-bot.vercel.app/0ezgif-2-da8e476e69.gif)

## Designing Our Desktop
You're back. You're refreshed. Maybe you even ate a strawberry or two 
~~(or maybe a whole package of strawberries)~~. 

### Adding The Desktop Background 
Adding the background is surprisingly easy! 

1. Find your image (I'll be using a photo I took in Michigan)
2. Drag it into Replit (the file manager)
3. On your body tag as the style property of `background-image: url(./NAME_OF_YOUR_IMAGE.png)`
4. Adding `background-size: cover;` to the body to make the size of the image fit the screen.
5. If your image still isn't quite fitting, add height: 100vh as a property to your body. This will make the height of the background 100% of the vertical height of your browser.

*(optional bonus challenge, try using a gif instead of a png)*

### Separating the Window from the Desktop
Alright well, this is looking beautiful!

Let's add a background color to our window so it looks visually distinct from the desktop. 

![background color added](https://cloud-4xp54hvar-hack-club-bot.vercel.app/0screenshot_2023-06-21_at_3.31.34_pm.png)

## Creating Our Top Bar
A top bar is generally used to display the name of the OS, key functions of a selected application, and the time. You can choose to display all or none of these pieces of information. You may also decide to give it different functions! 

I'll show you how you can add the name of the OS and the time. You can do whatever you want with it though!

### Creating the Foundation

Alright, let's start by just making a div (a group) to contain our top bar.

```html
<div>

</div>
```

### Horizontally Aligning The Elements

Now... let's add some text and make the text horizontally aligned (by using `display: flex` which by default places text into columns)

```html
    <div style="display: flex;">
        <p>
            ThomasOS
        </p> 
        <p>
            6/21/2023 3:41 PM
        </p>
    </div>
```

Note: Aye... I heard you want to master Flex. Is that right? If so, I CHALLENGE YOU (yes you) TO TAKE ON THE ULTIMATE FLEXBOX FROGGY CHALLENGE (basically tap [this link and play a super fun game to learn about flex](https://flexboxfroggy.com/))

### Customizing the Spacing

We can optionally space out the content by applying justify-content (check out [this justify-content testing site](https://www.w3schools.com/cssref/playdemo.php?filename=playcss_justify-content) to see how you can use justify-content to space out content)

![justify-content](https://cloud-e3m7dz3v0-hack-club-bot.vercel.app/0screenshot_2023-06-21_at_3.52.01_pm.png)
based on this demo, I decided I want to use space-between in the example below, but I encourage you to check out the testing site and pick what justify-content style works best for your design! 

```html
    <div style="display: flex; justify-content: space-between">
        (content)
    </div>
```

### Translucent Background
Now you can also add a semi-transparent background to your top bar by using RGBA. Try adding 

RGBA stands for Red, Green, Blue, Alpha where Alpha is the level of transparency (0 being fully transparent and 1 being no-transparency or opaque). You can also google RGB color picker and then manually write the transparency from 0 to 1. 

Here's an example.

```html
  <div
    style="position: absolute; width: 100%; display: flex; backdrop-filter: blur(10px); background-color: rgba(0, 0, 0, 0.25); color: #fff; justify-content: space-between;">
    <p style="margin-left: 16px;">
      ThomasOS
    </p>
    <p style="margin-right: 16px;">
      6/21/2023 3:41 PM
    </p>
  </div>
```

*Note: You'll also notice I threw in a backdrop-filter to blur the background. You can do that too!*

*Note: Please don't just copy this. Make it your own and make it look interesting in your visual aesthetic. This Jam is an absolute waste of your time if you're not experimenting and having fun while doing it. This isn't homework, this is your freedom, this is your art, this is your life! Enjoy it!*

### Personalize It

At this point, you don't need your hand held. Let's take off the training wheels and try making it look cool in your own way.

Here's how I decided to make mine look

![my top bar](https://cloud-5ozikpqtx-hack-club-bot.vercel.app/0screenshot_2023-06-21_at_4.19.33_pm.png)

I hope yours looks totally different!
Here's my code in case you want to take some inspiration from it. (but again, DON'T MAKE AN EXACT STYLE COPY) 
```html

  <div
    style="position: absolute; width: 100%; display: flex; backdrop-filter: blur(10px); background-color: rgba(0, 0, 0, 0.125); color: #fff; justify-content: space-between; gap: 32px;">
        <p
          style="margin-left: 16px; font-weight: 700; background-color: rgba(256, 256, 256, 0.125); padding: 4px 12px; border-radius: 16px;">
            ThomasOS
        </p>
        <p style="margin-left: 16px; background-color: rgba(256, 256, 256, 0.25); padding: 4px 12px; border-radius: 16px;">
            ☀️ Always Learning ☁️
        </p>
        <p
          style="margin-right: 16px; background-color: rgba(256, 256, 256, 0.125); padding: 4px 12px; border-radius: 16px;">
            6/21/2023 3:41 PM
        </p>
  </div>
```

Ideas to spice it up:
* Try different putting different content in the top bar
* Try a different color
* Try including more or fewer elements
* Include an image in your nav 
* Make it a bottom bar! (using the absolute positioning and the bottom property instead of the top property)

### Tracking The Time
I promised you JavaScript, so of course I am going to give you JavaScript.

JavaScript brings logic to your website. It's how your OS will respond to events (whether those be user events or events like the changing of time).

We can write JavaScript in its own file, or we can just write in the HTML file inside of a `<script>` tag. We're going to start inside the HTML file. 

#### Where Do I Write JavaScript? 

You can include your script tag in the HTML file. 

```html
<html>
    <body>
        (site content)
        <script>
            (JavaScript Code)
        </script>
    </body>
</html>
```

**At the moment we're going to be writing our code inside of our HTML file. We're not touching the script.js file yet *(until next Jam)***

![Write it in index.html](https://cloud-jajja5k48-hack-club-bot.vercel.app/0cat.png)

#### How Do I Get the Time? 

Let's begin by getting the time and storing it in a variable.

```html
<script>
    var currentTime = new Date().toLocaleString();
</script>
```

Alright, let's break this down. 

The var keyword indicates that we're creating a variable. 

currentTime is the name of the variable that we're creating. We could've given this variable any name (I encourage you to try naming it something else, just for fun).

new Date().toLocaleString(); is a browser function that gets the current date and formats it into plain text (what we hackers call a String). 

*Note: You don't need to know `new Date().toLocaleString`, you only need to know how to google "How do I get the current date as a String in JavaScript"*

#### How Do I Display the Time?
We have a value in JavaScript and we want to put it inside of our HTML text.

Here's how we go about doing that.

##### Mark the text we'd like to alter
Let's add an "id" to the time text so we can select it. Here's how that might look:
```html
    <p id="timeElement"
      style="(YOUR STYLES)">
      Time
    </p>
```

##### Select it in JavaScript
We can use a querySelector to select the element and store it in a variable. We pass into the querySelector the id of the element we're working with:

```html
<script>
    var currentTime = new Date().toLocaleString();
    var timeText = document.querySelector("#timeElement");
</script>
```
*Note: We placed a # in front of the id name to indicate it is an id*

##### Alter The Selected Element In JavaScript

Finally, we can set the innerHTML (the peanut butter in the bagel sandwich) and change the value (perhaps to cream cheese).

```html
<script>
    var currentTime = new Date().toLocaleString();
    var timeText = document.querySelector("#timeElement");
    timeText.innerHTML = currentTime
</script>   
```

![time being displayed](https://cloud-rl0do8tyh-hack-club-bot.vercel.app/0screenshot_2023-06-21_at_4.44.46_pm.png)

Boom, now we get the current time, but don't be too quick to celebrate. You'll notice the time doesn't update. This is because the code inside the script tag only runs a single time (when the page is first opened).

We need it to run every second. 

##### Make it run every second 
We can use the setInterval function to make the code repeat every 1000 milliseconds (every second).

Here's how we can go about doing that 
```html
  <script>

    function updateTime() {
        var currentTime = new Date().toLocaleString();
        var timeText = document.querySelector("#timeElement");
        timeText.innerHTML = currentTime;
    }
    setInterval(updateTime, 1000);

  </script>
```

I placed our previous code into a function (think of a function as an operation that we're telling the machine to run) and put that function inside of a setInterval (think of this as a robot that does the function every set amount of time). 

These five lines of code are very readable, but what if I told you there was a way to do it in just 3 lines line. 

Try updating the time every second in just three lines and then check the solution below

<Dropdown title="Solution">

```javascript
setInterval(function () {
  document.querySelector("#timeElement").innerHTML = new Date().toLocaleString();
}, 1000);
```

</Dropdown>

Lovely, here's what we've ended up with:

![PersonalOS](https://cloud-r3drmd84c-hack-club-bot.vercel.app/0screenshot_2023-06-21_at_4.59.32_pm.png)

For your final bonus challenge, try adding something interesting to your background. Maybe make it a gif?

Remember, this is your site.

Farewell, my dearest Hacker. 
I suspect we shall meet again... in the next Jam. 

What will be there?
That's for me to know and for you to find out 👀

Create Your OS Desktop & Top Bar (w/ a Clock)

Make Your Window Draggable, Closable, and Openable

Create Your First App


You didn't know it, but you've been riding a bike with training wheels. It's time we take off those training wheels and let you ride into the wind...

![riding into the wind](https://cloud-1cmmfb0q5-hack-club-bot.vercel.app/0the-penny-farthing-bike-race-vintage.gif)

Today you're going to be building an app for your personalOS and you'll be given pretty little guidance. **YOU GET TO DECIDE THE CONTENT AND FEATURES FOR THIS APP.** You're probably a bit nervous.

Don't worry, I'll be riding alongside you. I also don't know what app I am going to build. Fear not young one, we'll figure it out together. Be brave. You've been so brave up to this point and I am so proud of what you've built. Here's what I built, but I assure you that your final product will be nothing like this:

![final product](https://cloud-1ovz11fvq-hack-club-bot.vercel.app/0photo.gif)

Make sure you have some paper! Let's do this!

**Outline:** 
1. **Ideation** *(figure out what we're going to build)*
2. **Wireframe** *(make some sketches)*
3. **Build Your App** *(build an awesome app for our OS)*

## Ideation
You finally get to create your own app. It could be an app to do whatever you'd like! Here are some ideas (but I encourage you to come up with your own ideas):
* **Contact App** *(helps people get in contact w/ you)*
* **Projects App** *(shows all projects you've been)*
* **Map App** *(shows your life story on a map)*
* **Weather App** *(shows your local weather?)*

### Brainstorming on Paper
Let's begin by mind mapping on paper for ten minutes!

#### What is Mind Mapping?
A mind map is basically a visualization of a bunch of your ideas. It helps you be creative and explore ideas that would have otherwise never surfaced.

A question/prompt in the center of the map will provide us with some degree of direction and ideas will radiate from the center of our sheet. 

I found this example for you by browsing the internet:
![example of a mind map](https://cloud-i3lmaxn11-hack-club-bot.vercel.app/0image.png)
image from an [IDEO article about Mind Maps](https://www.ideo.com/blog/build-your-creative-confidence-mindmaps)

Your Mind Map doesn't have to be quite as big and crazy. Let's put in the center of our sheet of paper "What do I want people who visit my site to walk away knowing about me?." 

![question in the circle](https://cloud-dfm3s8clg-hack-club-bot.vercel.app/0img_1302-2.png)

When an answer comes to mind, draw it around the circle and then connect it to the center. Write down as many ideas as possible

![a new idea](https://cloud-ff7mcajxn-hack-club-bot.vercel.app/0img_1304.jpg)

Create a string of ideas & be sure to go for quantity over quality (no idea is too crazy for the mind map)

![question with some answers](https://cloud-on92ke5el-hack-club-bot.vercel.app/0img_1306.jpg)

& then go wild with it!

![complete mind map](https://cloud-bg351r0tv-hack-club-bot.vercel.app/0img_1309.jpg)

(your answers should & will be quite different than mine, and that's good) (have fun with it)

[Here's a ten minute timer](https://www.google.com/search?q=10min+timer&rlz=1C5CHFA_enUS1062US1062&oq=10min+timer+&gs_lcrp=EgZjaHJvbWUqCggAEAAYsQMYgAQyCggAEAAYsQMYgAQyBwgBEAAYgAQyBwgCEAAYgAQyBwgDEAAYgAQyBwgEEAAYgAQyBwgFEAAYgAQyBwgGEAAYgAQyBwgHEAAYgAQyBwgIEAAYgAQyCggJEAAYhgMYigXSAQgxMjc4ajBqNKgCALACAA&sourceid=chrome&ie=UTF-8), good luck!

#### Turning Brain Dump into ~~Beautiful~~ App

You probably now have an idea in your mind for something you'd love to convey inside your site after making that Mind Map. You may also have an idea for what that app would look like (if not, take a moment to consider what you might build to achieve your desired effect on the user).

I decided to try to create an image that contains almost every element of my life and then make it interactive so the user can tap on sections of the image to learn a bit more about me. Please make an app that is totally different! This app will be your App and should not look like my App. 

To begin, let's map out what a typical user experience will look like in terms of how they will flow through your App (this will vary depending on your App)

 ![App Flow](https://cloud-dxudaq5de-hack-club-bot.vercel.app/0img_1311.jpg)

Let's create a wireframe to flesh out our ideas a bit more.

## Wireframe
A wireframe is sort of a sketch of your app. You can sketch however you'd like, but the way I do it is by drawing shapes (like rectangles, circles, etc) that represent text, images, etc. 

![Insert image of the wireframe](https://cloud-1ungcc4hw-hack-club-bot.vercel.app/0img_1314.jpg)

Sketches are really just for you, so do whatever you like. Just make sure you can draw them as fast as possible.

I am also going to take a moment to ideate what items I would like to include in the image. This is a higher fidelity version of the initial wireframe. 

![](https://cloud-i8dp56cio-hack-club-bot.vercel.app/0img_1317.jpg)

Because I am not currently at home (I am at a Cafe across from Hack Club HQ), I am going to work with a prototype image. This will also just make it much easier to build the first version & then scale from there. 

![Empty Table](https://cloud-649y4sz8h-hack-club-bot.vercel.app/0img_1315.jpg)

I hope your app is totally different. If your app requires a lot of content that you don't have, try making it placeholder content for the time being. 

### Vision Secured
Awesome, hopefully you have secured your vision for the application. 

Next up, we'll be making the app icon & window (but it will be fast because of the work we did in our last Jam).

#### Creating App Icon
If we copy our previous icon and paste it beneath the previous icon...
![copy & paste](https://cloud-nl08nicka-hack-club-bot.vercel.app/0copypaste.gif)

wow, that was easy! Now we have our second icon on the screen!

Let's customize it to the name & image of our app! (import an image you'd like to use as your icon) (feel free to steal an image off the internet or create your own beautiful icon (or anything in-between))

![not tappable](https://cloud-p2xdz2i3j-hack-club-bot.vercel.app/0tap_icon.gif)

```
    <div id="photoIcon"
      style="text-align: center; margin: 8px; padding: 8px; filter: drop-shadow(0 0 8px black); width: fit-content; cursor: pointer;">
      <img src="./photo.png" style="width: 64px; height: 64px; border-radius: 16px;">
      <p style="margin: 0px; color: #fff; ">Life.png</p>
    </div>
```

Great, but now we're not able to tap on our icon! We need to initialize the icon.

Here's our old code:
```
var notesIcon = document.querySelector("#notesIcon")
var notesScreen = document.querySelector("#notes")

notesIcon.addEventListener("click", () => handleIconTap(notesIcon, notesScreen));

```

Let's try turning it into a function so we do not have to rewrite this code for our new icon. I challenge you to give it a shot! 

<Dropdown title="Solution">
    ```//Replace Old Code with This New Code
function initializeIcon(name) {
  var icon = document.querySelector("#" + name + "Icon")
  var screen = document.querySelector("#" + name)
  icon.addEventListener("click", () => handleIconTap(icon, screen));
}
initializeIcon("notes")
```

</Dropdown>

Now if you want to be really *nifty*, try making it so we initialize the window, we initialize the icon too 

(hint: it's only a 2-3 line change)

<Dropdown title="Solution">
    ```//Include initializeIcon function in initializeWindow for when it's not the welcome screen (because welcomeScreen has no icon)
function initializeWindow(elementName) {
  var screen = document.querySelector("#" + elementName)
  addWindowTapHandling(screen)
  makeClosable(elementName)
  dragElement(screen)
  if(elementName != "welcome") {
    initializeIcon(elementName)  
  }
}
initializeWindow("welcome")
initializeWindow("notes")
```
</Dropdown>

#### Creating Our App Window
Before we can initialize the window, we actually need to create it. Let's copy the code from the welcome window and then just delete the content and change the id of the application to the name of this app.

```

  <div class="window" id="photo" style="top: calc(50% - 90px); left: calc(50% - 180px); display: none; ">
    <div class="windowheader" id="photoheader">
      <div class="closebutton" id="photoclose">
      </div>

      <p class="headertext">Photo</p>
      <div style="width: 16px; margin-right: 6x; height: 16px;"></div>
    </div>
    <div style="background-color: #fff; margin: 6px; border-radius: 12px; width: 360px; padding: 16px;">
      <p>Hello World</p>
    </div>
  </div>
```

& then if in our javascript we call our initialize window function with our new app...

```
initializeWindow("photo")
```

BOOOYAHHHH, OUR SECOND WINDOW IS LIVEEEEEEEEEEEEE!!! WE'RE FULLY SETUP!
![new icon](https://cloud-96f6252ll-hack-club-bot.vercel.app/0newicon.gif)

## Build Your App
Okay now for the fun part... build your app. No hand holding here, you've built an app before and I know you can do it again. I encourage you to have fun & try to make an amazing app for your personalOS!

## You Built It, Congrats! 
Thanks for coming along this journey. I honestly was not expecting you to make it this far. Here's what my app ended up looking like:

![final product](https://cloud-1ovz11fvq-hack-club-bot.vercel.app/0photo.gif)

I hope you continue building apps for your personalOS & just generally have fun with it, but more importantly I hope you leave this batch with the urge to develop sites not just for yourself, but for other people! Building tools that help make the lives of others better is a task within reach given the fact that you made it all the way through this rigorous batch of Jams. I'm proud of you, and I hope you're proud of yourself. Have a great day, and keep Jamming!



Create an Advanced App

Create Your Personal Web-based Operating System

In this Jam, you'll be creating an awesome sword (or other item) in TinkerCAD. You will learn valuable skills around not only how to 3D model the sword example but also generally the ways designers think of their objects. Building something tangible while learning important concepts - two birds with one stone!


In this Jam, you'll be learning what CAD is, the functions of TinkerCAD, and learning how to make the blade of a medieval sword. You will have fun customizing your blade while learning both how to use TinkerCAD AND how to think like a 3D Modeler! 


Preparing Your Forge and Forging the Blade


![Excalibur?](https://cloud-jtvxpzl1c-hack-club-bot.vercel.app/0image.png)

*(Mountains and crystal models from TinkerCAD's Library)*

![woscenery](https://cloud-jtvxpzl1c-hack-club-bot.vercel.app/1image.png)

*(and now without scenery)*

*(The finished example sword. It's always possible to make more decorations!)*

After you have already learned the ways to use TinkerCAD from the last part, this is just going to move much faster and utilize the things you know.

And for ease of communication, from now on I will just call the longer non-height measurement of whatever shape as the length, and the shorter non-height measurement as the width. 

I'm also going to stop giving you rigid length measurements, to force you to be creative and find lengths and proportions you like.

Remember to use the handout from last time!

##  **Outline:**

1. **Deconstructing the Hilt** *(planning how to model the hilt)*
2. **Fusing the Pieces** *(finally putting everything together)*
3. **Armory of Legends** *(sharing your sword with your peers!)*

## Deconstructing the Hilt

Let's do a similar process with 

![Wikipedia Image of Sword Parts](https://cloud-jtvxpzl1c-hack-club-bot.vercel.app/2image.png)

When you are modeling (like when you are programming), it's always helpful to break big items into smaller parts. Modeling individual pieces and grouping them together is always easier than trying to do the whole thing. 

As such, let's break the hilt itself into the three key parts: the cross-guard, grip, and pommel.

Again, we have videos in the slides up top to guide you if you want to see how to make a basic hilt. But don't stick to the tutorial! We encourage putting as much creativity as you can muster into this project!

Here's some good resources to look at various hilts and gain inspiration!
http://myarmoury.com/feature_hilts.html 
https://swordencyclopedia.com/sword-hilt/
https://www.metmuseum.org/art/collection/search?showOnly=highlights&sortOrder=asc&sortBy=Relevance&department=4&material=Arms

### Cross Guard

Let's take a look at a real one

![Cross Guard Sample Image](https://swordencyclopedia.com/wp-content/uploads/2023/06/Crossguard-Sword-Title.jpg)

(David Mickov, 6-7-2023, "The Different Crossguard Sword Types and Styles From Europe • Sword Encyclopedia," Sword Encyclopedia, https://swordencyclopedia.com/crossguard-sword/)

It looks already quite simple, but we can make it simpler. It's basically the same as the blade (a diamond prism shape) but stretched way wider and being shorter.

![Hilt Base](https://cloud-lpi8legia-hack-club-bot.vercel.app/0image.png)

If you wanted a straight handguard, we are done. But we can do better than that. 

A problem with TinkerCAD is that it's hard to curve objects that aren't already curved. However, remember that we have a lot of shapes that we can work with, and remember the three key ways we can make a weird shape:

- Combine a few shapes (Addition)
- Subtract shapes from each other (Subtraction)
- Deform another shape to make what you want (Modification)

In this case, let's try subtraction since it's hard to add a curve or do anything with deforming shapes in TinkerCAD. 

Let's grab a cylinder and rotate it 90 degrees. Stretch it out lengthwise and decrease its height to make its curve more gradual. 

![Cylinder Modifying](https://cloud-lpi8legia-hack-club-bot.vercel.app/1image.png)

Let's duplicate it (either by using Ctrl C and Ctrl V, or just Ctrl D). Move it so that they are barely touching, and use our old friend the align tool to, well, align them. 

![Align](https://cloud-lpi8legia-hack-club-bot.vercel.app/2image.png)

Notice how I will only click the red dot (align width-wise) and not the middle dot on the long side, since that will just make them overlap. We get this:

![Cyl2](https://cloud-lpi8legia-hack-club-bot.vercel.app/3image.png)

Group them, and align them with the red hilt body. You can make a few adjustments to the height and length of the cylinder abomination, and make sure to move it up a bit since we want to cut the top, not the bottom of the red shape.

![Example](https://cloud-lpi8legia-hack-club-bot.vercel.app/4image.png)

Now we address what you see here: Holes. 

![Holes](https://cloud-lpi8legia-hack-club-bot.vercel.app/5image.png)

You're probably wondering how we can do subtraction, if so far all I showed you is combining two shapes into one. To that I say, we use **holes**. 

Grouping a hole with a solid cuts holes in it. Let's make the orange shape a hole, and then use the group tool on it and the red shape. 

Before the grouping:
![pregroup](https://cloud-lpi8legia-hack-club-bot.vercel.app/6image.png)

After the grouping:
![postgroup](https://cloud-lpi8legia-hack-club-bot.vercel.app/7image.png)

A small tip with holes: remember that you can use an object you've already cut shapes out of as another hole! 



#### Optional Challenge with this tip in mind

With this technique I made the bottom curve as well. Try to figure out how I did that as a challenge, or simply move on if you'd like. 

![chal](https://cloud-lpi8legia-hack-club-bot.vercel.app/8image.png)

Great! You've made it past the most difficult part! You can stay here to decorate more, but for our purposes (whether you did the challenge or not) this hilt is more than enough. Now let's move on. 

### Grip

This is much easier. All we need is a cylinder that shrinks as you get higher. If you want to be technical about it, this is called a frustum, or in our case a cone frustum.

... Oh wait that isn't a pre-made shape? Let's make it then!

If you search up frustum you will probably see diagrams like this:

![Cone Frustum](https://cloud-fb5vv4641-hack-club-bot.vercel.app/0image.png)

Hey, isn't that just a cone but with the tip cut out? We can do that with holes!

Since you already know how to use holes (and are probably tired with my rambling), I'm not going to elaborate much. I'll just show pictures.

![frust1](https://cloud-fb5vv4641-hack-club-bot.vercel.app/1image.png)

![f2](https://cloud-fb5vv4641-hack-club-bot.vercel.app/2image.png)

Easy right? Shapes like this gets easier and easier to identify as you model more and more.

### Pommel

The pommel is probably the most flexible bit of the sword. As such, I highly suggest you come up with your original idea.

I'm just going to show some pictures of me making an easy cylinder pommel if you run out of cool ideas. 

This simple cylinder pommel is just making each part separately, aligning and fusing. The tutorial video in the slides gives an even easier example that doesn't even include the center sphere.

![c1](https://cloud-cof3vpycd-hack-club-bot.vercel.app/0image.png)

![c2](https://cloud-cof3vpycd-hack-club-bot.vercel.app/1image.png)

![c3](https://cloud-cof3vpycd-hack-club-bot.vercel.app/2image.png)


## Fusing the Pieces

Let's look at our inventory.

![Inventory](https://cloud-bl0ftjpng-hack-club-bot.vercel.app/0image.png)

(I just made all of them a bit smaller because TinkerCAD was yelling at me about a size limit... oops)

A video of the fusing process is within the slides again, but this is basically just repeating what you did countless times before in order to put pieces together.

After some resizing and combination, we are (FINALLY) done!

![End product](https://cloud-bl0ftjpng-hack-club-bot.vercel.app/1image.png)

(You can recolor parts by ungrouping it, then recoloring each piece by selecting it, clicking the "solid" button, and pressing a different color.)

Fit for a king!

## Armory of Legends

Now, let's go ahead and show your swords to your peers! 

Marvel at the creativity and skills of both yourself and those around you!

You can even think of unique powers for your swords, and write them into Dungeons and Dragons magic items!

Here's a cool website for that: <a href="https://homebrewery.naturalcrit.com/"> https://homebrewery.naturalcrit.com/ </a>

## Next steps???

If you want to move on with more modeling, there are many different ways to move forward!

First, I would recommend the "Build your own 3D club village" Jam by linkai101! It involves the use of Spline, a slightly more advanced web-based system. 

It is here: <a href="https://code-jams.hackclub.dev/jam/3d-club-village"> https://code-jams.hackclub.dev/jam/3d-club-village </a>.

### Other Programs

One of the most common applications used by casual modelers is Blender, a free open-sourced modeling application. It requires downloading, though. Its devs are very good, and it regularly receives updates to introduce more functionality or make your experience better. 

It's website is <a href="https://www.blender.org/"> blender.org </a>. 

PROS:
1. Really good for visual things (when you want something to look cool but don’t need it to work well as a piece of something)
2. Functionality (has everything needed and can edit shapes in ways that other software cannot)
3. Lots of tutorials (and a great documentation) online to follow if you are stuck
4. Always Free

CONS:
1. Cannot model parts if you are asking for precise measurement
2. Takes a while to get used to all of its functionality
3. Needs a download

Professional and industry modelers commonly use AutoDesk's Fusion 360, a paid modeling application that's really advanced and involves multiple simulation types. It also requires downloading, and normally costs quite a lot. However, some schools that partner with AutoDesk may have those for free! Check with whoever manages tech at your school to see if you can access Fusion for free!

It's website is <a href="https://www.autodesk.com/campaigns/education/fusion-360"> here </a>. 

PROS:
1. Really good for precise measurement parts
2. Easy to learn, 99% of the time you’re using 2 functions
3. Professional level, good for college applications or resume
4. Lots of ways to assemble parts together within the application before you print

CONS:
1. Hard to model things that look good on the level of Blender
2. Hard to find tutorials that address the specific issue you have
3. Hard to start learning (but gets easier once you get the basics)
4. Only free for students, will not be free if you continue it after you graduate

Overall, AutoDesk has a lot of really good CAD applications, but most of them cost money unless you have a school subscription.

### A Word of Thanks!

Thanks again for choosing this Jam and for choosing the wonderful world of 3D modeling! 

Today, you built on your past skills and learned how to create the rest of the sword!

Next, you can try more complicated software, like Blender or Fusion 360.

Now go and make your dreams come true! Happy Crafting!!


In this Jam, you will be finishing the hilt of the sword that we made in the last jam part. You will have fun customizing your product while learning both how to use TinkerCAD AND how to think like a 3D Modeler! 


Crafting Weapons, Shields, and Armor in TinkerCAD

Forge of Legends: Crafting Weapons, Shields, and Armor in TinkerCAD

Let's build our own AI companion! My companion is going to be Orpheus (you might have heard of her ;) but by the end of this jam, you'll have your own AI best friend.


### Part 1/4 | Prerequisite: a little web dev knowledge (HTML, JS, CSS) | 30-45 minutes

So what is artificial intelligence and machine learning? And what can you do with them?

<video src="https://cloud-ckyxamknp-hack-club-bot.vercel.app/0jams_gifs__1_.mp4" controls="controls" style={{maxWidth: "720px"}}></video>
*(here's an example of what you'll create by the end of this jams. Your AI & ML model will be unique to you and serve a completely different purpose!)*

**We're going to be making an AI Companion or Smart Voice Assistant in your browser!**

My companion is going to be Orpheus! [You may have heard of her.](https://workshops.hackclub.com/orpheus/) Believe it or not you will be able to create this project by the end of this jams no matter how much background knowledge you have already! And your project will be entirely yours (take advantage of that creative freedom)!

Here are some ideas for your AI Companion:
- create an AI smart assistant that will constantly disagree with you and critique you
- create an AI relationship if you're quite lonely
- create an AI project manager that helps you schedule your day
- create an AI friend who you can have dinner with (again, if you're quite lonely)
- create an AI cooking companion who will walk you through steps while you're in the kitchen
- create an AI pet
- create an AI teacher who will give you lectures

This AI project will be completely web-based using HTML, JS, and CSS as well as tools such as Teachable Machine by Google and Replit. We'll also go over step-by-step instructions on how to incorporate OpenAI API into our project!

**In this part, we'll start with an introduction into machine learning as well as our Teachable Machine model! By the end of today, you'll have made and trained your own ML model to recognize an audio or visual keyword.**

[Live Demo ](https://ai-jams-official.sahitid.repl.co) **(Make sure to input your own API Key if you want it to work!)**
[Sample Code](https://replit.com/@sahitid/AI-Jams-Official)**(Make sure to input your own API Key if you want it to work!)**
[Sample Teachable Model](https://teachablemachine.withgoogle.com/models/hiSl8IOc-/)

### **Outline:**
1. **Overview of Project** *(bird's eye view on the entire project)*
2. **Get Started with Teachable Machine** *(train your own machine learning tool in your browser)*
3. **Create Your Classes** *(decide what activates your AI companion)*
4. **Train Your Model** *(add/create training data for your teachable machine*
5. **Finish and Export!**
6. **Enter The Code Editor** *(start coding in your browser)*
7. **Onto the JS!**
8. **Add Some Boilerplate HTML**

## Overview of Project

You may be familiar already with smart voice assistants such as Siri, Alexa, or Google Home. All these technologies utilize artificial intelligence to generate and complete messages.

You will be building a similar program. Call it, and it will turn on. It will turn your speech into text, and then input your transcript into a GPT model (through an API). The GPT model will then create a response which is turned into speech. The program will essentially talk back to you.

![diagram detailing the parts of our project](https://cloud-essfp77oh-hack-club-bot.vercel.app/0group_1.png)

In this part, we'll be training the model to detect when the keyword is evoked with Teachable Machine.

## Get Started with Teachable Machine!

We're going to be starting with teachable machine, a web-based tool that allows you to train your own machine learning model without any coding required.

We want to make sure that our AI Companion can recognize an audio or visual keyword! Just like a smart voice assistant:

![](https://cloud-iosp3gjlp-hack-club-bot.vercel.app/0image.png)

Head over to [Teachable Machine](https://teachablemachine.withgoogle.com/train) and create a new project. I'm going to be creating an audio project! Keep in mind that you can use any of the three projects; your keyword could be a key-hand-motion or key-object that is held in front of the camera.

Anything that is obvious enough to be detected in order to prompt the AI Companion will work here!

![teachable machine dashboard](https://cloud-cffjo14g3-hack-club-bot.vercel.app/0screenshot_2023-06-27_154600.png)

Once you choose your project from the dashboard, you should see the different classes. Let's focus on what we want to train the model to learn/look out for first.

## Create Your Classes

I want my AI Orpheus to respond to me whenever I say "Orpheus". Rename Class 2 to match your keyword, and don't copy mine! Your AI Companion should be completely your own.

![renaming teachable machine classes](https://cloud-jefx2fwob-hack-club-bot.vercel.app/0teachable.gif)

It's almost as if you have two piles of stickers. Think of each sticker as a sample of training data.

You can add existing stickers (or samples) to the piles (or classes) to make it more clear what the characteristics of each class are.

![two piles of stickers](https://cloud-7cg6bj1c5-hack-club-bot.vercel.app/0img_8125.jpg)

Then the machine learning model can take and entirely new sample that you give it as input and use the data in the existing classes to sort it.

![sorting stickers into respective piles based on existing data](https://cloud-jjpf3syuu-hack-club-bot.vercel.app/0jams_gifs__1_.gif)

## Train Your Model

Now it's time to train! If you're doing an image or pose model click on "Webcam" and then hold to take a burst of photos. If you're doing an audio project, click the "Mic" button to record short clips of your keyword being said.

*Tip: the best training data set has multiple variations of the same sample in different settings.*

The minimum number of samples based on the project type is listed. But remember more data = better accuracy of model.

If I had even more stickers in the piles it would be even easier to sort new stickers that I got because there would be more data to evaluate from! 

### Now record and extract sample data

Also make sure to record lots of silence and background noise as well in different settings (in a classroom, hallway, outside, alone, etc) so the model is good at detecting when nothing is being said. We want there to be a clear distinction between when the keyword is said vs. when it is not said.

![adding audio samples to teachable machine classes](https://cloud-lmzin6jbg-hack-club-bot.vercel.app/0website_gifs.gif)

## Finish and Export

And tada! Once you're done click the "Train Model" button. Now you have a fully working machine learning model.

And you don't have to stop there: try creating another class that'll make it easier to differentiate what is or isn't the keyword even further. 

For example, I know the word "amorphous" sort of sounds like Orpheus, but isn't exactly the keyword. Currently, the model still gets a little confused and assumes that someone saying "amorphous" is partially saying Orpheus.

![false keyword detected](https://cloud-3kt0jz704-hack-club-bot.vercel.app/0screenshot_2023-06-28_105128.png)

I'm going to make a separate class for the word "amorphous" so it no longer confuses the model.

Back to our sticker and basket analogy, this is just me creating another basket so people aren't confused on where to put stickers when sorting them.

![sorting sticker into wrong pile](https://cloud-b0mbeaace-hack-club-bot.vercel.app/0ad30c6eb-346a-4ba3-aa9e-954783f524a9_1.gif)

Look at the image below. Now the model is less confused when I say the similar-sounding-but-not-actually-the-keyword word.

![teachable machine recognizes false keyword](https://cloud-hvxyjcxd6-hack-club-bot.vercel.app/0screenshot_2023-06-28_105711.png)

You've essentially created another pile!

![sorting sticker into correct pile](https://cloud-mjrezffaw-hack-club-bot.vercel.app/0975da332-06c1-4bf0-95d7-e35546326741.gif)

### Click the Export Model Button

Once you're here you should see an "Update my cloud model" button. Make sure you do this!

![update my cloud model button](https://cloud-crblb6kcm-hack-club-bot.vercel.app/0screenshot_2023-06-28_142611.png)

Now you can show off your work by sending people the shareable link.

To finish our model we'll **copy the shareable link as well as the tensorflow.js JavaScript** that's given below.

Make sure to save your teachable machine to drive so it can be accessed later. Next time, instead of creating a new project, you can open this existing project from drive.

![saving project to drive](https://cloud-iibkonedk-hack-club-bot.vercel.app/0image.png)

Great! Now you've finished with the teachable machine. You've trained a machine learning model with a dataset to understand and recognize when it's being called to "turn on".

Now let's implement the model into a program so you can interact with it.

## Enter the Code Editor

Firstly, let's get setup in the code editor! Head over to the [Replit Website](https://replit.com/languages/html) and create an account.


<Dropdown title="What is Replit?">
Replit is a web-based independent development environment (IDE). It's essentially a code editor in your browser that will instantly deploy your site to the entire world
</Dropdown>

If you're having difficulty using the site try https://firewalledreplit.com/ or even an alternative like [Glitch](https://glitch.com/)

### Create a New Replit Project

Welcome to your Replit Dashboard. Once inside, tap "+ Creat a Repl" and then select the HTML, CSS, and JavaScript template.  

![Replit Signup](https://cloud-c6z75ah46-hack-club-bot.vercel.app/0export_jun_15_2023_0159_pm.gif)

You should now have three files. Rename them to be: index.html, script.js, and style.css respectively.

## Onto the JS!

Let's skip the HTML/CSS for now. We'll head straight over to `script.js` or the JavaScript file and add this initial code:

``` js
const URL = 'INSERT TEACHABLE MACHINE URL HERE'
const THRESHOLD = 0.9
```

Yay! We've just created the following two constants:
1. `URL` represents the URL of the Teachable Machine model we will be using
2. `THRESHOLD` represents the confidence threshold for recognizing a specific word

![teachable machine output](https://cloud-f437a9orj-hack-club-bot.vercel.app/0image.png)
*(Feel free to set the threshold number to any amount you like! I've got it set for 90% or higher accuracy in recognition. This is essentially that output bar you see moving in the teachable machine).*

Now we are going to create one big function that all the other functions + our teachable machine code will sit inside. It's an event handler that runs once the window is finished loading to ensure that the code inside only runs after all the HTML content has been loaded:
```js
window.onload = () => {
  let recognizer;
}
```

**This is where we will add pieces of the Tensorflow.js file that we got after exporting the teachable machine model.**

We should also go ahead and declare the recognizer variable (this pops up later).

```js
let recognizer;
```

Now we're going to create a `createModel()` function that's responsible for loading the Teachable Machine model. It creates a new instance of the `speechCommands` object and uses the provided `URL` to set the model topology and metadata URLs. It then calls the `ensureModelLoaded()` function to ensure that the model and metadata are loaded via HTTPS requests.

```js
async function createModel() {
  const checkpointURL = URL + 'model.json'
  const metadataURL = URL + 'metadata.json'

  const recognizer = speechCommands.create(
    'BROWSER_FFT',
    undefined,
    checkpointURL,
    metadataURL
  )

  await recognizer.ensureModelLoaded()
  return recognizer
}
```

*Tip: If you're ever stuck or confused ~~or have a spelling mistake in your code that your IDE isn't catching but continues to break the whole program~~, try asking [AI such as ChatGPT](https://chat.openai.com/) to figure it out for you!*

And next, we can create the `init()` function for initializing the speech recognition process. It awaits the `createModel()` function to load the model and assigns it to the `recognizer` variable. Then, it calls the `listen()` function on the `recognizer` object.

```js
async function init() {
  recognizer = await createModel()
}
```

The `listen()` function will reside in the `init()` function and takes two arguments. The first argument is a callback function that is invoked when a word is recognized. In this case, it checks the score of the recognized word at index 1 (index 1 corresponds to the trigger word in the Teachable Machine model) and compares it with the `THRESHOLD` value. If the score is higher than the threshold, it logs "Hey" to the console.

The second argument is a configuration object that allows you to customize the behavior of the speech recognition. It includes options such as

- `includeSpectrogram`: determines whether the `listen()` function should return the spectrogram (a visual representation of the frequencies present in an audio signal over time) data along with the recognition result.
- `probabilityThreshold`: the accuracy threshold or minimum confidence score that a recognized word must have to be considered a valid recognition. You can adjust this value to have a higher threshold (stricter recognition) or a lower threshold (more lenient) based on your requirements.
- `invokeCallbackOnNoiseAndUnknown`: determines whether the callback function should be invoked when the recognized word is considered noise or unknown. When set to `true`, the callback function will be triggered even when the recognized word is not part of the trained vocabulary or if it is classified as noise.
- `overlapFactor`: value between 0 (no overlap) and 1 (complete overlap) that controls the amount of overlap between consecutive analysis frames during the recognition process. Higher overlap values can provide better accuracy but might introduce a slight delay in processing.

```js
async function init() {
recognizer = await createModel()

recognizer.listen(
    result => {
      const orpheusNoise = result.scores[1]
      if (orpheusNoise > THRESHOLD) {
        console.log("Hey")
      }
    },
    {
      includeSpectrogram: true,
      probabilityThreshold: 0.75,
      invokeCallbackOnNoiseAndUnknown: true,
      overlapFactor: 0.5
    }
)}
```
*(These are just what I put as the options, but feel free to mess around with them! I also suggest that you keep the `overlapFactor` between 0.5 and 0.75 for best accuracy & speed!)*

Note that the code inside the `init()` function is not executed immediately but is defined to be executed later when the window finishes loading.

Full code:
```js
const URL = 'INSERT TEACHABLE MACHINE URL HERE'
const THRESHOLD = 0.9

window.onload = () => {
  //copy and paste our Teachable Machine model here!
  let recognizer;

  async function createModel() {
    const checkpointURL = URL + 'model.json'
    const metadataURL = URL + 'metadata.json'
    
    const recognizer = speechCommands.create(
      'BROWSER_FFT',
      undefined,
      checkpointURL,
      metadataURL
    )

    await recognizer.ensureModelLoaded()

    return recognizer
  }
  
  async function init() {
    recognizer = await createModel()

    recognizer.listen(
      result => {
        const orpheusNoise = result.scores[1]
        if (orpheusNoise > THRESHOLD) {
          console.log("Hey")
        }
      },
      {
        includeSpectrogram: true,
        probabilityThreshold: 0.75,
        invokeCallbackOnNoiseAndUnknown: true,
        overlapFactor: 0.5
      }
    )
  }
}
```

Take a minute and look back at the Tensorflow.js code that you had the option of copying a few steps ago when you exported the Teachable machine. Can you tell where each function that you wrote ✨*all by yourself*✨ came from?

*All this code above has come directly from the teachable machine Tensorflow.js file!*

## Add Some Boilerplate HTML

Open the index.html file! Replit will give you some template code already, but replace that with *my* template code ~~because it's better~~.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Orpheus</title>
    <link rel="stylesheet" href="/styles.css" />
  </head>
  <body>
    <div>
      <div>
        <script src="/script.js"></script>
      </div>
    </div>
  </body>
</html>

```

You should notice that everything here is about standard, and that the three files (HTML, JS, and CSS) are now connected to each other.

But there's one last step we need to complete in order to incorporate the Teachable Machine model. Add the following code to the `<head>`:

```html
<script src="https://cdn.jsdelivr.net/npm/@tensorflow/tfjs@1.3.1/dist/tf.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@tensorflow-models/speech-commands@0.5.4/dist/speech-commands.min.js"></script>
```

## Great! Now Run Your Program

Now on Replit open up your HTML "site" in a new tab. don't worry if it's blank! It's supposed to be since we don't have many elements on it. 

Now click ctrl+shift+i to open the inspect element and move to the console tab. If you look under choices you'll be able to see the text that has come back!

![console printing response to keyword being said](https://cloud-2sz1omo3w-hack-club-bot.vercel.app/0image.png)

Yay! Now watch the console print "Hey" every time you say the keyword!

## Additional Challenge Hacking! (recommended)

The creation doesn't have to stop here! Here are some Jam Hacks™ that you can experiment with:
![jam hacks](https://cloud-f7mhrygov-hack-club-bot.vercel.app/0jam_hacks_2.gif)

- I've made the keyword an audio one but what if we tried using a visual/image model instead? *(My friend Thomas is testing to see what would happen if the teachable machine was trained to notice if you raised your hand or waved a flag!*)
- What would happen if you added multiple keywords?
- Try someone else's teachable machine model! Do you think you could confuse it.
- I know I said I'd recommend the `overlapFactor` between 0.5 and 0.75 for best accuracy & speed, but in what scenario would having a slower and more accurate model be more appropriate? And vice versa

And again, the best model is one that is trained with a lot of data! Always use diverse variations.

## Stay Tuned To Build Your Very Own Smart Voice Assistant

Okay, now that we've spent time to train our model to recognize *when* to listen let's implement it into a program that controls *how* it listens and *what* it will do with that information.

Also, printing in the console is boring, let's make it talk back to us out loud!

In the next part we will build the foundation of our AI companion by implementing a speech to text recognition API.


This is a workshop description introducing the concept of Artificial Intelligence and Machine Learning, focusing on creating a web-based AI Companion or Smart Voice Assistant using HTML, JS, and CSS, as well as tools like Teachable Machine by Google and Replit, and incorporating OpenAI API to recognize an audio or visual keyword, with examples of different ideas for AI Companions.


Beginning the Foundation with Machine Learning 


### Part 2/4 | Prerequisite: a little web dev knowledge (HTML, JS, CSS) | 45-60 minutes

Yay! I'm so glad you're continuing this adventure to build your own AI Companion!

Although this Jams goes over the fundamentals of using AI and ML, reign all your creative freedom to create a fully functioning smart assistant. I'm making an [Orpheus](https://workshops.hackclub.com/orpheus/) that'll embody Hack Club's mascot but you certainly don't have to.

In fact I encourage that you go out of your way to think of the most bizarre uses of your program. Take a look at what an AI came up with as ideas.

![chatgpt response with ideas for projects](https://cloud-jmwnkv7lq-hack-club-bot.vercel.app/0image.png)

In this part, we'll start coding our web app with JavaScript and HTML to set up our speech to text feature, start listening function, and stop listening function!

### **Outline:**
1. **Enter The Code Editor** *(start coding in your browser)*
2. **Set Up the HTML Some More** *(visualize the conversation with AI)*
3. **Let's Get Orpheus to Speak!** *(text to speech recognition!)*

## Enter the Code Editor

Firstly, let's get setup in the code editor! Head over to the [Replit Website](https://replit.com/languages/html) and open the project you were working in the last part of this Jams.

You should see your 3 files: index.html, script.js, and style.css respectively.

## Set Up the HTML Some More

Now let's get Orpheus to speak instead of a boring `console.log`.

There are two parts to this: 1) we want to hear it, but 2) we also want to see it, so we need to edit the HTML now.

That's easy! Go to `index.html` and add this to the `<body>`

```html
<body>
    <div id="startup">&middot; &middot; &middot;</div>
    <div id="messages"></div>
    <div id="loading">&middot; &middot; &middot;</div>
    <div id="result">&middot; &middot; &middot;</div>
</body>
```

Don't be scared of HTML entities! They are just descriptions for different symbols, here we are using the middle dot symbol (`middot` or . ) to represent loading bubble.

The `messages` div will store all the messages between us and Orpheus, `startup` is the initial loading of the Teachable Machine model, `loading` is for Orpheus' responses, and `result` is our responses.

Some of these will be invisible at first, so let's add some CSS:

```css
#result,
#loading {
  display: none;
}
```

## Let's Get Orpheus to Speak!

![orpheus plushie gif](https://cloud-lsz4bcbfi-hack-club-bot.vercel.app/0jams_gifs.gif)

Now we can create the two functions to first output the response through text onto the screen and then to output the speech

We will create 2 functions, one to output Orpheus' response to the screen and the other one to actually speak:

Okay, let's get Orpheus to speak now! We will create 2 functions in the JavaScript file, one to output Orpheus' response to the screen:

```js
function addMessage({ role, content }) {
  let message = document.createElement('div')
  message.innerText = content
  message.scrollIntoView(false) // Scroll to the message
}
```
*Here we are destructuring the argument because OpenAI returns responses as `{role, content}`* 

And the other one to actually speak:

It will be an async function, which means it runs asynchronously: talking takes time and we want to make sure it finishes talking before we move onto the next thing. To do this, we use _promises_, which tell us when a function is done running and whether or not it was successful.

```js
async function speak(message) {
  return new Promise((resolve, reject) => {
    let synth = window.speechSynthesis
    if (synth) {
      let utterance = new SpeechSynthesisUtterance(message)
      
      synth.cancel()
      synth.speak(utterance)
      utterance.onend = resolve
    } else {
      reject('speechSynthesis not supported')
    }
  })
}
```

The `speak` function takes a `message` as input and returns a promise. Inside the function, it checks if the browser supports speech synthesis. If it does, it proceeds with converting the `message` into speech.

It then creates a speech utterance (to represent the text to be spoken) and sets it up with options like voice and speaking rate (which are currently commented out in the code), and cancels any ongoing speech synthesis process.

Also, if the browser doesn't support speech synthesis, it rejects the promise with a message saying that speech synthesis is not supported.

#### Change Up Your AI Companion's Voice

Additionally, if you play around and add some lines of code under  `let utterance = new SpeechSynthesisUtterance(message)` you can change up the voice of your AI Companion. And there's lots of voices to choose from!

There are a lot of voices to choose from:

```js
const voices = synth.getVoices()
utterance.voice = voices[voices.findIndex(voice => voice.name === 'Good News')]
utterance.rate = 1
```

Play around with the voices! You can find a list of some voices [here](https://codepen.io/matt-west/full/DpmMgE). *(Try out Good News, it's hilarious!)*

And finally, let's edit up our already existing `listen` function:

```js
recognizer.listen(
  result => {
    const orpheusNoise = result.scores[1]
    if (orpheusNoise > THRESHOLD) {
      speak('Hey').then(() => {
        console.log("Done speaking")
      })
    }
  },
  {
    includeSpectrogram: true,
    probabilityThreshold: 0.75,
    invokeCallbackOnNoiseAndUnknown: true,
    overlapFactor: 0.5
  }
)
```

In case it wasn't obvious enough, here is what we changed:

![before and after for code](https://cloud-8s76y8brd-hack-club-bot.vercel.app/0jams_gifs.png)

Notice that we replaced `console.log` with `speak('Hey!').then(() => ...)`. Because we used promises, we can say, once speak is done done running, we can **then** move on to the next thing, which is `console.log`ging "Done speaking

We need to also implement the `listening` variable so that Orpheus isn't listening and speaking at the same time that it is listening! It will tell Orpheus whether or not she should be speaking or listening *(that way, listening doens't overlap with Orpheus speaking, which could lead to problems).*

Initialize the following variable at the beginning of your program:

```js 
let listening = false
```

Now incorporate it in the `listen` function:
```js
recognizer.listen(
  result => {
    const orpheusNoise = result.scores[1]
    if (orpheusNoise > THRESHOLD && !listening) {
      listening = true
      speak('Hey').then(() => {
        console.log("Done speaking")
        listening = false
      })
    }
  },
  {
    includeSpectrogram: true,
    probabilityThreshold: 0.75,
    invokeCallbackOnNoiseAndUnknown: true,
    overlapFactor: 0.5
  }
)
```

And finally we need to call the `init` function at the end!

```js
init()
```

## Full Code and Demo

```js
const URL = 'https://teachablemachine.withgoogle.com/models/hiSl8IOc-/'
const THRESHOLD = 0.9

let listening = false

async function speak(message) {
  return new Promise((resolve, reject) => {
    let synth = window.speechSynthesis
    if (synth) {
      let utterance = new SpeechSynthesisUtterance(message)
      const voices = synth.getVoices()
      utterance.voice = voices[voices.findIndex(voice => voice.name === 'Good News')]
      utterance.rate = 1
      synth.cancel()
      synth.speak(utterance)
      utterance.onend = resolve
    } else {
      reject('speechSynthesis not supported')
    }
  })
}

function addMessage({ role, content }) {
  let message = document.createElement('div')
  message.innerText = content
  message.scrollIntoView(false)
}

window.onload = () => {
  let recognizer;

  async function createModel() {
    const checkpointURL = URL + 'model.json'
    const metadataURL = URL + 'metadata.json'

    const recognizer = speechCommands.create(
      'BROWSER_FFT',
      undefined,
      checkpointURL,
      metadataURL
    )

    await recognizer.ensureModelLoaded()

    return recognizer
  }

  async function init() {
    recognizer = await createModel()

    recognizer.listen(
      result => {
        const orpheusNoise = result.scores[1]
        if (orpheusNoise > THRESHOLD && !listening) {
          listening = true
          speak('Hey').then(() => {
            console.log("Done speaking")
            listening = false
          })
        }
      },
      {
        includeSpectrogram: true,
        probabilityThreshold: 0.75,
        invokeCallbackOnNoiseAndUnknown: true,
        overlapFactor: 0.5
      }
    )
  }

  init()
}
```

<video src="https://cloud-18r0fzw3m-hack-club-bot.vercel.app/0jams_gifs__1_.mp4" controls="controls" style={{maxWidth: "720px"}}></video>

## Additional Challenge Hacking! (recommended)

It's that time you've all been waiting for! Let's Hack our Jam! Try doing one of the following:
![jam hacks](https://cloud-f7mhrygov-hack-club-bot.vercel.app/0jam_hacks_2.gif)

- Try adding a setting that lets people choose their voice option
- Have you ever looked into [Eleven Labs](https://beta.elevenlabs.io/) AI voices? How might one go about incorporating their API into this project for more realistic voices?
- Could you add a setting that lets people choose their assistant's voice when they open your web app?

## Stay Tuned To Build Your Very Own Smart Voice Assistant

We just gave our model a voice and the necessary tools to know *when* to listen. But we still need to give it the functionality to understand language and speech.

In the next part, we'll integrate the speech recognition API to convert our speech to text for the AI Companion to understand.


Giving Your Smart AI Companion a Voice!


### Part 3/4 | Prerequisite: a little web dev knowledge (HTML, JS, CSS) | 45-60 minutes

Welcome back to our little journey to create a walking talking Orpheus AI Companion *(but of course, your own AI Companion will serve its own purpose to you)*.

## First Let's RECAP

In the first part of the Jams, we used Teachable machine to train a model in order to recognize the keyword "Orpheus". We then used the Replit online IDE to create an empty site that would print a message in the console every time the keyword was detected to be said.

![console printing response to keyword being said](https://cloud-2sz1omo3w-hack-club-bot.vercel.app/0image.png)

In the second part of the Jams, we gave Orpheus a voice! Now instead of printing out a message in the console, our AI Companion would speak and say it out loud.

<video src="https://cloud-18r0fzw3m-hack-club-bot.vercel.app/0jams_gifs__1_.mp4" controls="controls" style={{maxWidth: "720px"}}></video>
Now in the third part of the Jams, we will allow Orpheus to convert the speech that we say when we talk to it into text.

*Reminder: If you're ever stuck or confused ~~or have a spelling mistake in your code that your IDE isn't catching but continues to break the whole program~~, try asking [AI such as ChatGPT](https://chat.openai.com/) to figure it out for you!*

### **Outline:**
1. **Enter The Code Editor** *(start coding in your browser)*
2. **Set Up the HTML Some More** *(visualize the conversation with AI)*
3. **Let's Get Orpheus to Speak!** *(text to speech recognition!)*

First let's store the history of our messages in our:

```js
let messages = []
```

Go in and update the `addMessage` function.

```js
function addMessage({ role, content }) {
  let message = document.createElement('div')
  message.innerText = content
  document.getElementById("messages").appendChild(message);
  
  if (role === 'user') message.classList.add('user')
  else message.classList.add('system')
  document.getElementById('messages').appendChild(message)
  message.scrollIntoView(false) // Scroll to the message
}

```

Now we are going to add a new async function that we're calling `hear`. Essentially, we are:

- Creating new instance of `SpeechRecognition()`
- Starting it with `recognition.start()`
- Adding an event listener to it so that when the user is done speaking, so we can get a transcript of what the user said
- Stopping the listening with `recognition.stop()`
- And finally, returning the transcript successfully

``` js
async function hear() {
  return new Promise((resolve, reject) => {
    let SpeechRecognition =
      window.SpeechRecognition || window.webkitSpeechRecognition
    let recognition = new SpeechRecognition()
    recognition.start()
    recognition.addEventListener('result', function (event) {
      let current = event.resultIndex
      let transcript = event.results[current][0].transcript
      recognition.stop()
      resolve(transcript)

    })
  })
}
```

Now we can actually put it to use! We are going to edit the `recognizer.listen` function again so that after Orpheus says "Hey", she will start listening to us. This is how the code will look now:

```js
recognizer.listen(
  result => {
    const orpheusNoise = result.scores[1]
    if (orpheusNoise > THRESHOLD && !listening) {
      listening = true
      speak('Hey!').then(() => {
        hear().then(response => {
          console.log(response)
        })
      })
    }
  },
  {
    includeSpectrogram: true,
    probabilityThreshold: 0.75,
    invokeCallbackOnNoiseAndUnknown: true,
    overlapFactor: 0.5
  }
)
```

Here's the edit you just made, if it's not obvious enough.

![before and after image](https://cloud-oqe6fu130-hack-club-bot.vercel.app/0jams_gifs.png)

## See It In Action!

Now when you refresh the page, you should see the flow come to life:

Try saying the keyword and Orpheus will say "Hey" back.

Now try saying something else to your AI Companion and watch as it `console.log`s what you said! Woah! 

![console.log of speech](https://cloud-mzlajhso5-hack-club-bot.vercel.app/0image.png)

And now do you see how useful promises are? We can wait for `speak()` to finish before we start `hear()`ing, and then only after the computer is done hearing do we log the message.

The last thing to do in this workshop is to get this message to the screen when the user is done. We do also want to show a loading bubble while we're speaking. Here's how the final `recognizer.listen` function will look like:

```js
recognizer.listen(
  result => {
    const orpheusNoise = result.scores[1]
    if (orpheusNoise > THRESHOLD && !listening) {
      listening = true
      speak('Hey!').then(() => {
        document.getElementById('result').style.display = 'block'
        hear().then(response => {
          document.getElementById('result').style.display = 'none'

          let message = { role: 'user', content: response }
          addMessage(message)
          document.getElementById('loading').style.display = 'block'
          
        })
      })
    }
  },
  {
    includeSpectrogram: true,
    probabilityThreshold: 0.75,
    invokeCallbackOnNoiseAndUnknown: true,
    overlapFactor: 0.5
  }
)
```

Now the process is:
1. Say hi to Orpheus
2. Orpheus responds "Hey"
3. Our bubble pops up
4. We start talking
5. The loading bubble disappears and our message shows up on the screen

Yay! Now Orpheus can hear you and convert your voice into text.

![final demo of speech being printed as text on screen](https://cloud-d37x8o6qj-hack-club-bot.vercel.app/0image.png)

## Additional Challenge Hacking! (recommended)

It's that time you've all been waiting for! Let's Hack our Jam! Try doing one of the following:
![jam hacks](https://cloud-f7mhrygov-hack-club-bot.vercel.app/0jam_hacks_2.gif)

- Change up your character! We're doing Orpheus but you don't have to.
- Our UI is also going to look like a smart phone & text messaging system. But I encourage everyone to do their own play on this AI Companion. What if your screen has a sound visualizer?

## Stay Tuned To Build Your Very Own Smart Voice Assistant

We now have a model that can understand what we are saying and convert that speech into text. But a good friend can't just listen! They also need to talk back!

In the next part, we'll dive deeper into APIs and integrate the OpenAI GPT-3.5 language model for chat completions. This is the most pivotal step and will give our AI Companion the skill of having a conversation with us.


Teaching your AI companion to listen to your voice


### Part 4/4 | Prerequisite: a little web dev knowledge (HTML, JS, CSS) | 45-60 minutes

## Let's RECAP

In the first part of the Jams, we used Teachable machine to train a model in order to recognize the keyword "Orpheus". We then used the Replit online IDE to create an empty site that would print a message in the console every time the keyword was detected to be said.

![console printing response to keyword being said](https://cloud-2sz1omo3w-hack-club-bot.vercel.app/0image.png)

In the second part of the Jams, we gave Orpheus a voice! Now instead of printing out a message in the console, our AI Companion would speak and say it out loud.

<video src="https://cloud-18r0fzw3m-hack-club-bot.vercel.app/0jams_gifs__1_.mp4" controls="controls" style={{maxWidth: "720px"}}></video>
In the third part of the Jams, we gave Orpheus the power to convert our speech into text.

Now, in the fourth and final part, we will finally incorporate the OpenAI API to utilize the GPT 3.5 model. Ever heard of ChatGPT? OpenAI built it and invested years and billions of dollars to create the dataset that you will be using for your AI Companion.

### **Outline:**
1. **Set-Up and Get Your API Key** *(quick intro into APIs)*
2. **Idea Generation** *(set up idea generation with the OpenAI API)*
3. **Now Text Completion!** *(set up text completion with the OpenAI API)*
4. **Final Function**

## Set-Up and Get Your API Key:

1. Make an account and login to https://platform.openai.com/
2. Go to API keys and create a new API key. *Make sure to save it! never share it! As you can see in the demo, we haven't provided our own API key in the project for this reason.*

![API keys on OpenAI](https://cloud-n3hgshowm-hack-club-bot.vercel.app/0image.png)

We will be using GPT-3.5 or GPT-4, the most accessible and recently updated set of models that can understand & generate both natural language and code. There are also [models](https://platform.openai.com/docs/models/overview) such as Whisper (that can convert audio into text) or Dall-e (that can generate and edit images based on a prompt).

##### There's Two Parts to Implementing a Text Model
Firstly, the AI needs to be able to generate its own ideas. Next, the AI must complete text suggestions, such as how Google tries to guess what you're searching.

![google autocomplete](https://cloud-ae241kl1y-hack-club-bot.vercel.app/0image.png)

This will allow us to have a conversation with the AI!

## Idea Generation

1. Use this endpoint: 
`POST https://api.openai.com/v1/completions`

APIs are really simple! there's 4 main requests for HTTP request methods:

> APIs (or Application Programming Interfaces) are like a digital restaurant, they are the waiter that goes between you (the client) and the kitchen (the server). Requests are sent from you the client to the server to perform actions.

![digital restaurant gif](https://cloud-lk53rqdly-hack-club-bot.vercel.app/0bb312c00-400b-4da4-bc6a-6fbd2a91cca4.gif)

<table>
  <thead>
    <tr>
      <th>Method</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>GET</td>
      <td>Retrieve information</td>
    </tr>
    <tr>
      <td>POST</td>
      <td>Send information</td>
    </tr>
    <tr>
      <td>PUT/PATCH</td>
      <td>Update information</td>
    </tr>
    <tr>
      <td>DELETE</td>
      <td>Delete information</td>
    </tr>
  </tbody>
</table>


2. Here we are fetching the API and using the post method to send information:

``` js
fetch("https://api.openai.com/v1/completions", {  
	method: "POST",  
	headers: {  
	Authorization: `Bearer ${API_KEY}`,
	"Content-Type": "application/json"  
	},  
	body: JSON.stringify()  
})
```

3.  Let's add what model we're using *(this is the only not optional step)*! remember you can find a list of all models here, but only some can be used for text completion and generation.

```js
fetch("https://api.openai.com/v1/completions", {  
	method: "POST",  
	headers: {  
	Authorization: `Bearer ${API_KEY}`,
	"Content-Type": "application/json"  
	},  
	body: JSON.stringify({
		model: "gpt-3.5-turbo"
	})  
})
```

4. Next let's put in a prompt. this will be a string that will be sent to the API to generate text for

```js
fetch("https://api.openai.com/v1/completions", {  
	method: "POST",  
	headers: {  
	Authorization: `Bearer ${API_KEY}`,
	"Content-Type": "application/json"  
	},  
	body: JSON.stringify({
		model: "gpt-3.5-turbo",
		prompt: "hi! how are you?"
	})  
})
```

5. Next we'll add `max_tokens`  to take an integer value for the largest value of tokens to generate in the completion.
```js
fetch("https://api.openai.com/v1/completions", {  
	method: "POST",  
	headers: {  
	Authorization: `Bearer ${API_KEY}`,
	"Content-Type": "application/json"  
	},  
	body: JSON.stringify({
		model: "gpt-3.5-turbo",
		prompt: "what should i do today?",
		max_tokens: 6
	})  
})
```

Tokens are common sequences of characters found in text and what the models use to process it.

The OpenAI tokenizer (https://platform.openai.com/tokenizer) can be used to visually demonstrate how an API would tokenize a string of text, as well as how many tokens it would be.

![tokenizer](https://cloud-1sxrk5p2x-hack-club-bot.vercel.app/0image.png)

*General rule: 1 token generally corresponds to ~4 characters of text for common English text or 3/4 of a word. this is roughly 100 tokens ~= 75 words.*

6. Here are a few more options that you can use! pick and choose from the following to see what they can do: 

| Name | Description | Restrictions |
| -------- | -------- | -------- | 
| temperature | this is a value from zero to two, where higher values will make the output more random, and lower values will make the output more focused and deterministic. | cannot be used with top_p 
| top_p | nucleus sample: where the model only considers the tokens with the top_p probability mass | cannot be used with temperature |
| n | allows us to assert how many completions are generated for each prompt | doing this will take more tokens, so be mindful
| user | will represent end-user to help openai detect/monitor abuse |
*Check out [OpenAI API Documentation](https://platform.openai.com/docs/api-reference/chat) for more options that you can use!*

## Now Let's Add Some Code!

*Tip: If you feel like you ever need help or someone to double-check your work during any part of the following process, feel free to "pair-program" with ChatGPT! Just copy and paste your code and question into the box and read the AI's reply.*

Go to our script.js file and make a new function called `answer` to insert our fetch request in!

```js
async function answer(message) {
	return new Promise((resolve, reject) => {

	}
}
```

Let's create a function called fetchData and make is async.

```js
async function fetchData(){

}
```

Now inside the brackets type `const response = await fetch()` to save the fetched data in the constant variable response. Go to the [documentation](https://platform.openai.com/docs/api-reference/completions) and get that URL that is stated and put it in the `fetch()`.

Your code should now look like this. This goes to the completions endpoint.

```js
async function fetchData(){
	const response = await fetch("https://api.openai.com/v1/completions")
}
```

3. Next we're going to pass through all our options that we were looking at before. so in the curly brackets let's pass through the method (a post method) as well as some headers.

```js
async function fetchData(){
	const response = await fetch("https://api.openai.com/v1/completions",{
		method: "POST",
		headers:{
			
		}	
	})
}
```

But what goes in headers? For starters our API key needs to be passed through, and for that we'll use authorization.

Back at the beginning of the code, let's create another constant to store that string of letters and numbers that you retrieved from openai earlier:

```js
const API_KEY = "insert your private API KEY here"
```
And in the headers brackets add this line:

```js
Authorization: 'Bearer' ${API_KEY},
```

4. Now let's also define our content type in the brackets and we're going to be working with json.

```js
"Content-Type: "application/json"
```

You should now have this:

```js
const API_KEY = "insert your private API KEY here"
async function fetchData(){
	const response = await fetch("https://api.openai.com/v1/completions", {
	method: "POST",
	headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },  
	
	})
}
```

5. We're going to have to pass through the options that we saw after the headers. We're using json to pass the text and "text-davinci-003" as the model for now (we will change this to gpt-3.5 or gpt-4 later).

```js
body: JSON.stringify({
      model: "text-davinci-003",
      prompt: "what should i do today?",
      max_token: 6
    })
```

6. And now finally, we are going to get the response as json, but since it's also an async method we have to use await and save it in a variable. and of course, let's use `alert` to display the data as an alert on screen.

```js
const data = await response.json()
alert(data)
```

Check your code!

```js
const API_KEY = "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"
async function fetchData() {
  const response = await fetch("https://api.openai.com/v1/completions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "text-davinci-003",
      prompt: "what should i do today?",
      max_token: 6
    })
  })
  const data = await response.json()
  alert(data)
}
```

But there's one last important step: call your function, silly!
```js
fetchData()
```

## Now Text Completion

Let's use this knowledge to build an AI that also supports text completion. This will allow us to have full conversations with the AI.

I'll be using gpt-3.5 as my model this time.

And our new endpoint will be `POST https://api.openai.com/v1/chat/completions` (note: /chat for chat completions)

1. Make sure all the required things are added into the script.js file (from the last section):
	- the API key which you must retrieve and save in an variable
	- the content type
	- and the model (all models here: https://platform.openai.com/docs/models)

```js
const API_KEY = "insert your private API key here"
async function fetchData() {
  const response = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "gpt-3.5-turbo",
    })
  })
}
```

2. An additional requirement this time is to include `messages`. messages are a list of messages comprising the conversation so far. [Example Python code](https://github.com/openai/openai-cookbook/blob/main/examples/How_to_format_inputs_to_ChatGPT_models.ipynb)

```js
messages:[{
        role: "user",
        content:"Hello!"
      }]
```

3. Now let's put that data somewhere and call the function you just made.

```js
const data = await response.json()
console.log(data)
```

Full code:
```js
const API_KEY = "insert your private API key here"
async function fetchData() {
  const response = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "gpt-3.5-turbo",
      messages:[{
        role: "user",
        content:"Hello!"
      }]
    })
  })
  const data = await response.json()
  console.log(data)
}

fetchData()
```

## Final Function

Okay, great, but we need to use the function. The first thing we'll do is create one last function (I promise!) called `process` so our code doesn't get too messy:

```js
async function process() {
  document.getElementById('result').style.display = 'block'

  hear().then(result => {
    document.getElementById('result').style.display = 'none'

    let message = { role: 'user', content: result }
    addMessage(message)
    document.getElementById('loading').style.display = 'block'

    answer(message).then(response => {
      response.role = 'system'

      messages.push(response)
      addMessage(response)

      document.getElementById('loading').style.display = 'none'

      speak(response.content).then(() => {
        process()
      })
    })
  })
}
```

So this is mostly the code that was in our `recognizer.listen` function. Except we added a couple parts. First up, we are now using `answer` to respond to the message.

Once we have an answer, we use `addMessage` to add it to the screen, and then use `speak` so Orpheus can speak it out loud.

After Orpheus is done speaking, we can repeat the process, so the computer will keep listening to us.

And finally, let's replace `recognizer.listen` now:

```js
recognizer.listen(
  result => {
    const orpheusNoise = result.scores[1]
    if (orpheusNoise > THRESHOLD && !listening) {
      listening = true
      speak('Hey!').then(() => {
        process()
      })
    }
  },
  {
    includeSpectrogram: true,
    probabilityThreshold: 0.75,
    invokeCallbackOnNoiseAndUnknown: true,
    overlapFactor: 0.5
  }
)
```

Woah, now it works! Talk to Orpheus.

## Final Demo

We went further and customized ours to look like a phone, but I encourage you to go out and create your own styling :

```css
@import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');

* {
  box-sizing: border-box;
}

body,
html {
  background-color: #fafafa;
  font-family: -apple-system, 'Roboto', sans-serif;
  margin: 0;
  padding: 2rem 0;
  display: flex;
  align-items: center;
  justify-content: center;
}

#phone {
  aspect-ratio: 1 / 2;
  box-shadow: 0 8px 16px 0 rgba(0, 0, 0, 0.4);
  width: 375px;
  border: 14px solid black;
  border-radius: 28px;
}

#container {
  position: relative;
  background-color: white;
  width: 100%;
  height: 100%;
  border-radius: 14px;
  border: 1px solid white;
  overflow-y: auto;
}

#header {
  background-color: rgba(255, 255, 255, 0.5);
  -webkit-backdrop-filter: blur(2em);
  backdrop-filter: blur(2em);
  position: sticky;
  top: 0;
  border-bottom: 1px solid #e5e5e5;
  text-align: center;
  padding-top: 0.5rem;
}

#header img {
  width: 80px;
}

#header p {
  margin-top: -10px;
}

#wrapper {
  display: flex;
  flex-direction: column;
  padding: 1rem 0.5rem;
}

#messages {
  display: flex;
  flex-direction: column;
}

.user {
  background-color: #09f;
  color: white;
  padding: 7px 14px;
  border-radius: 14px;
  align-self: flex-end;
  margin-bottom: 7px;
}

.system {
  background-color: #eee;
  padding: 7px 14px;
  border-radius: 14px;
  margin-bottom: 7px;
  align-self: flex-start;
}

#result,
#loading {
  display: none;
}

```

## Final Demo
<video src="https://cloud-ckyxamknp-hack-club-bot.vercel.app/0jams_gifs__1_.mp4" controls="controls" style={{maxWidth: "720px"}}></video>

## Additional Challenge Hacking! (recommended)

It's that time you've all been waiting for! Let's Hack our Jam! Try doing one of the following:
![jam hacks](https://cloud-f7mhrygov-hack-club-bot.vercel.app/0jam_hacks_2.gif)

Use any one of the APIs in your own project. Here are some examples:

- DIY transcript app by connecting YouTube videos to SpeechRecognition API!
- Train Teachable Machine to do other things! JC has a guitar so she was thinking of recognizing chords to make her own Guitar Hero
- What if you had a password to unlock your assistant? Train Teachable Machine to recognize you drawing digits in the air to unlock your assistant!
- Redesign the UI! Ours is a phone but maybe yours is Jarvis
- Add messages to `localStorage` so your AI can remember what it asked you last time!

## Congratulations!

You've created a project with artificial intelligence and machine learning. Now go forth and be hacky!

![orpheus celebration dance](https://cloud-12ntu5q74-hack-club-bot.vercel.app/0jams_gifs__1_.gif)


Giving Your Smart AI Companion a Body and Brain!

Create Your Own Smart AI Voice Companion

Ever wondered how your phone knows when you tilt it? What makes an Arduino tick? With this jam, you'll level up your circuit skills by building your own Arduino-compatible level PCB! You can use it to measure angles, decorate your room, or do anything you can with an Arduino!


Let's design an Arduino Nano-compatible microcontroller board using KiCAD!

If you follow through these 4 jams, your finished SparkleTilt will look something like this - but with your very own design customizations!

![](https://cloud-izep2lpej-hack-club-bot.vercel.app/031picture.jpg)


<details>

<summary>Video Demo</summary>

<iframe width="560" height="315" rel="0" src="https://www.youtube-nocookie.com/embed/px2V8bZMeLI" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</details>

## Prerequisites

If you are not already familiar with the basics of using an ECAD tool like EasyEDA or KiCAD, check out another jam like [the PCB Hacker card](../../../jam/hacker-card). The rest of this workshop will assume you know how to draw a schematic from pictures.

{/* Ideally a better version of this video will be made by a Hack Clubber, but this is the best basic video we have now */}
[This YouTube video](https://www.youtube.com/watch?v=EPH23zhPg50) demonstrates the basics of navigating around KiCAD.

In addition, the rest of the workshop assumes you know basic electronics terms like:
1. Resistor: A resistor limits the electric current that flows through a circuit. Resistance is the restriction of current.
2. Capacitor: A capacitor stores charge, and thus energy. It's like a tiny battery that charges and discharges very quickly.
3. Diode: A diode only allows current to flow in one direction. It also drops a little bit of voltage, turning that energy into heat.
2. Microcontroller: A microcontroller (aka MCU) is a system on a chip that contains an integrated processor, memory, and input/output peripherals, which are used to interact with other electronic components.

## Part Selection

Step 0 of designing a board is to clearly define what problem you need the board to solve. Here, we are making a nice looking level. The primary goal is to demonstrate electronics and PCB concepts. A secondary goal is to have an attractive and fun level.

Step 1 of designing a board is selecting your core components:

1. Microcontroller: ATmega328P. The ATmega series is the most robust and common 8-bit MCUs, being used in many Arduinos since the beginning. Additionally, it requires very few external components and runs over a wide range of voltages (1.8V-5.5V). It's also one of the very few microcontrollers that is a *Basic Part* on JLCPCB. And, it's available in a QFP package so it can be hand-soldered. It doesn't have many fancy features, but it's simple and robust.

2. USB-Serial Interface: CH340N. Because the ATmega328P doesn't have a built-in USB interface, we need a USB-UART IC. The CH340C worked well for @Hugo[^1], and it's very cheap, so I'm using the CH340N. The CH340N is the cheapest IC from the CH340 series that has an integrated clock, meaning fewer components are needed.

3. Pinout: While not technically a component, we will follow the standard Arduino Nano pinout. This really doesn't matter— unless you value your future self's sanity when trying to wire up new components.

Now on to the actual circuit.
Make sure you have KiCAD downloaded, then set up a new project, and open the schematic editor.

## Core (Microcontroller)

First, we place the heart of our system, the ATmega328P-AU, in a TQFP package [Search: ATmega328P-A]. This is NOT the ATmega328PB, which is not backward compatible with the ATmega328P.

### Power

![](https://cloud-j48wmzjac-hack-club-bot.vercel.app/21.webp)

Then, we need to connect the power pins to power *nets* and place *decoupling capacitors*.

**Nets**: Nets like VCC and GND serve as abstractions for actual connections in our schematic. If we connected every single chip to a central VCC and GND point in our schematic, it would be very messy. These symbols tell the PCB Designer that we need to connect those pins while keeping the schematic clean.

**Decoupling Capacitors**: AKA Bypass Capacitors. A decoupling capacitor is placed very close to the chip that needs or supplies power. When a chip suddenly demands power, it provides it while the battery and other components ramp up, essentially like a dam controls a river. When there are voltage spikes or noise, it absorbs them, while letting normal DC power pass along. So, these have to be as physically close to their parent IC as possible in the PCB layout (in Part 2).

In the KiCAD parts list, search `C` and after placing it change the *value* field to the correct number and units, 100nF in this case.

Your *reference designator* numbers for C may be different from the image (C1 and C2). VCC and GND are also parts that can be imported like any other parts. And feel free to delete the labels on GND to reduce clutter.

### Clock

![](https://cloud-j48wmzjac-hack-club-bot.vercel.app/32.webp)
The datasheet for our crystal, C13738, shows that pins 2 and 4 are connected to ground [Search: Crystal_GND24].

Now that our MCU is powered, it needs a clock to tick to[^3]. We can configure the ATmega328P to use this 16MHz crystal rather than run at its default of 1MHz.

This crystal needs an accompanying capacitor connected to ground on each pin. 

<details>

<summary>How did I come up with the value of these capacitors?</summary>

```
C = 2 * CL - CS
```
Here, C is the capacitor we need, CL is the load capacitance specified by the crystal manufacturer, and CS is the stray capacitance of the microcontroller pin. In our case CL (of the crystal) is 9pF and CS (of XTAL1/2) is 6pF (as specified by the datasheet).

So, we use 12pF capacitors.
</details>

[^3]: Yes, while the ATmega328P does have an internal clock, it's kinda inaccurate and could cause issues with serial communications. The simple and safe choice is to use an external crystal which are typically accurate to 20 parts per million, a opposed to the 5% (5 parts per hundred) of the ATmega's intenal clock.

### Reset
![](https://cloud-j48wmzjac-hack-club-bot.vercel.app/43.webp)

The bar on top of RESET means that it is active low, GND (0V) will reset the MCU and it should be at VCC (5V) during normal operation. The SPST button here is JLCPCB's basic push button which connects RESET to ground when pressed [Search: SW_SPST]. 

The resistor R6 [Search: R] is a pull-up resistor, a high-resistance resistor that gently pulls the RESET pin HIGH without passing too much current through it. This allows the switch to pull the RESET pin down without causing a short circuit, while preventing random noise from pulling RESET down.

Labeling this wire as RESET connects it to the RESET *net*. If we place another RESET label somewhere else on this page, our ECAD tool will understand that these two points have to be connected, just like the GND and VCC nets. Press "L" to activate the label tool.


### Label Pinout

![image](https://cloud-j48wmzjac-hack-club-bot.vercel.app/54.webp)

After this, we need labels telling us which MCU pin is which Arduino Nano pin.

These are global labels. Unlike the RESET label, these work on all pages of the schematic. You can press "CTRL+L" to create a gloabl label.

## Headers

![](https://cloud-nbfq15yho-hack-club-bot.vercel.app/15.png)

First, we have the traditional Arduino Nano pinout [Search: Arduino_Nano_v3] connected to our labels, telling the ECAD software we want these headers connected to the prespecified microcontroller pins. Since this whole board is running at 5V, just mark 3V3 as NC (No Connect).

We also have the ICSP header [Search: Conn_02x03_Odd_Even], which is used for flashing the Arduino's bootloader. It has all the SPI pins in one neat package, MISO, MOSI, SCK, RESET, VCC, GND.

Once you have a label, you can press 'x' to flip it horizontally.

## USB

We start with the 16 Pin USB 2.0 Type C receptacle, C165948.

![image](https://cloud-mu5k1d6dk-hack-club-bot.vercel.app/1usb.png)

NC: SBU1/2 and Shield/Shell (shield is only for hosts).

GND goes to our ground net.

Mark VBUS with a net, and then run it through a diode [Search: D] to the VCC net, which powers everything else on this board. 

Since we will be powering a bunch of LEDs, I picked a big diode JLCPCB had as a basic part, C35722. Set the *value* field to the part number so you can find it later. This diode prevents current from going back into your computer if both USB and 5V pins are plugged in.

Then, to tell the USB-C port that we are drawing power from it, CC1 and CC2 have to each be connected through separate 5.1k resistors to ground[^4]. That tells the USB-C power adapter that we can draw up to 5V 3A.

You can download the KiCAD CH340N footprint here: [ch340n.kicad_sym](https://cloud-b6v3rkn29-hack-club-bot.vercel.app/0ch340n.kicad_sym). Then, put it in your project folder and add it to your symbol library in Preferences > Manage Symbol Libraries > Project Specific Libraries.

![](https://cloud-j48wmzjac-hack-club-bot.vercel.app/87.1.webp)
![](https://cloud-j48wmzjac-hack-club-bot.vercel.app/97.2.webp)

![image](https://cloud-mu5k1d6dk-hack-club-bot.vercel.app/0ch.png)

Now, we can connect our UART chip, the CH340N. Both D+ and D- from the USB-C connector go to D+/- on the CH340N. As specified in its datasheet, both V3 and VCC get 100nF decoupling capacitors. RTS goes to RESET through another 100nF capacitor; this capacitor makes the RESET pin briefly pulse low instead of staying low forever (avoiding bootlooping the MCU).

RXD and TXD (USB directionality), are connected to their microcontroller pins D1 (MCU's TX) and D0 (MCU's RX) respectively with some status LEDs [Search: LED, Value: GREEN/YELLOW].

[^4]: 5k1 is just a concise and clear EE way of saying 5.1k. The units are context dependent, so here it means kilo - ohms.

## Done!

Now you have a simple Arduino Nano-compatible board schematic! Check out Part 2 to turn this into a PCB, or jump to Part 3 to add more features to this board[^2].

![](https://cloud-mu5k1d6dk-hack-club-bot.vercel.app/201full-kicad.svg)

{/* footnotes */}

[^1]: Thanks to Hugo Hu for his instructable, this schematic is based on that design: https://www.instructables.com/ATmega328P-Corgi-Arduino/

[^2]: **WARNING**: You will need another microcontroller board to flash the bootloader on this ATmega328P before you can program this board. Ask in Slack if you have ANY questions about this.


Design an Arduino Nano-compatible microcontroller board in KiCAD

Microcontroller Circuit Design

Turn a microcontroller schematic into a real PCB layout

Turn a KiCAD Schematic into a PCB

Add useful sensors, chargers, and lights to your dev board

Adding Peripherals


In this jam, we will take a KiCAD PCB and order it through JLCPCB with assembly[^2].

If you're just jumping in, make sure you have your [DRC checked](./part-2#Design%20Rules%20Checker) from Part 2 of this jam series.


Here are some component notes[^3]:
- The grant allows you to purchase anything from one of the allowed suppliers, including JLCPCB.
- One of JLCPCB's sister/partner companies, LCSC, stocks virtually every generic component you'd ever need, and all of them can be assembled.
- Keep in mind that JLCPCB charges a $3 fee for every "extended component" type that they assemble.
- You will not be able to get specialized components from Adafruit or similar companies through the grant.
- A complete library of JLCPCB/LCSC components is available at [jlcpcb.com/parts](https://jlcpcb.com/parts).
- If following the ATMega328P workshop, you will need an Arduino, FTDI board, or any other AVR programmer to flash the bootloader before you can use the board's USB port. Verify what you need for your chip. ESP32s and RP2040s typically work out of the box.

## Install the Extension

Click on Plugin Manager on the KiCAD home page.

![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/111.webp)

Search for 'JLC'.

![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/122.webp)

Install 'Fabrication Toolkit' and apply changes.


## Assign Part Numbers

Open your schematic. Go to Bulk Edit fields.

![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/135.webp)

In the Field Editor window, click on 'Add Field' and add the field `LCSC`. It doesn't matter whether you have `Sim.*` or `Datasheet` fields or not.

![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/146.webp)

Then, search for your components at [jlcpcb.com/parts](https://jlcpcb.com/parts) and fill in the LCSC id.

For generic components, search for the Value and Footprint - `100nF 0805` - and check basic parts. You'll see a couple of different voltages, pick the lower (cheaper) one since we are only at 5V.

You don't *have* to necessarily specify the part number for generic components like 0805 resistors or capacitors, but I prefer to manually select it rather than leave it up to JLCPCB to decide.

The LCSC Part number (aka JLCPCB Part #) looks like `Cxxxx`.

![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/157.webp)

For more specific components, like the Atmega328P-AU, you should only have a couple of options and just pick the most popular one (Basic Part if possible).

![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/168.webp)


Try doing this yourself before you look at my version below.

<details>

<summary>This is what your table should look like, and then Apply and Save.</summary>

![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/179.webp)

Because A1 and J2 aren't real components - we only need their footprint and pin layout, not the component itself - they don't need an LCSC part number.
</details>
  
## Export files

Now, go back to the PCB view and sync it.

![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/110.webp)

Then, click on Tools > External Plugins > Fabrication Toolkit.


![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/211.webp)

Everything you need to order your board will now be in `your_kicad_project/production/`.

![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/312.webp)

Now, log in to [jlcpcb.com](https://jlcpcb.com). Go to [cart.jlcpcb.com/quote](https://cart.jlcpcb.com/quote) and upload `gerber.zip` into "Add Gerber file".

You should see something like this:
![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/413.webp)

Tips:
- 5 is the minimum number of PCBs you can order.
- You can change your shipping option on the right 'Shipping Estimate' sidebar.
- Sometimes, reducing the PCB thickness from 1.6 to ~1.0 will reduce the weight of the package, and thus the shipping price without increasing manufacturing price.
- If your PCB will be handled a lot consider selecting 'LeadFree HASL' for its surface; excessive exposure to lead can be toxic.

Leave the 'High-spec options' at their defaults, and then, enable assembly. 
- You can choose to only assemble 2 boards out of 5, in which case the other 3 bare boards will be shipped to you. If you only want one PCB, this can save money on parts.
- You can only assemble one side in Economic PCB assembly.
- Standard PCB assembly with both sides is very expensive  (~$65) and will use up most of your grant money. Try to design PCBs that have components on one side and don't use any 'Standard Only' components. Or, solder the other side by hand.


![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/514.webp)
Then, on the Bill of Materials page, upload bom.csv and positions.csv from your production folder. 

![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/716.webp)

- You can save a lot of money on Extended Parts in the long run (if you plan on making many PCBs) by buying them directly and soldering them yourself [^1]. For example, basically every project has a USB-C connector and header pins, so it makes sense to buy a bunch yourself and avoid the $3 extended part fee every time you buy a board from JLCPCB.
- Virtual Components (only used for their through holes) like the Arduino Nano and ICSP header can be ignored.

![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/817.webp)
When it prompts you about unselected parts, just click 'Do not place'.

Zoom into your components on the 'Component Placements' screen and rotate them to the correct orientation if they're wrong.

If you get all parts assembled, this board (from part 2)[^4] ends up being around $33.

![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/918.webp)

With shipping, that's $45 for me.

![](https://cloud-9ctvo6cbs-hack-club-bot.vercel.app/1019.webp)

[^1]: You might want to edit the footprints of components you are hand-soldering. For example, to hand solder the USB-C connector, make the pads longer and remove unused ones like SBUS.
[^2]: There are a million different ways to export your files and order with different manufacturers, but for simplicity, this jam only focuses on one.
[^3]: by [@camdan.me](https://hackclub.slack.com/team/U04J96SRS5B)
[^4]: This is just the microcontroller board from parts 1 and 2. It does not include any of the peripherals such as th LEDs and accelerometer.

Learn how to convert a board design into an actual order

Ordering a KiCAD board from JLCPCB

SparkleTilt: Design a Digital Level PCB

Get started making your very first game with the Sprig game engine, using JavaScript! Sprig is a great tool for both beginners and advanced programmers, and if you make a game, you can get a free DIY handheld console! Follow this four-part series in order, and you'll get to make your very own puzzle game.


At Hack Club we believe strongly that the best way to learn to code is by making creative, interesting, meaningful projects. Sprig is a project by Hack Club that enables anyone to do just that - we've created a web editor that both beginners and more advanced programmers can have fun making games in, and an accompanying handheld console that you can get for free by publishing your own game!

By the end of today's session, we'll be making our first project in Sprig: a [Sokoban](https://en.wikipedia.org/wiki/Sokoban)-style push block game!

### Outline:
1. What's Sprig?
2. Let's explore the Sprig editor!
3. Build Your First Game!
4. Wrap-up!

## 1. What's Sprig?

![](https://sprig.hackclub.com/stories-tiny/sprig-front.jpeg)

Sprig is a game editor, game engine and handheld gaming console all built by Hack Club. To learn more about how these were made, take a look at [Sprig's GitHub](https://github.com/hackclub/sprig)!

### What level of programming is required to make Sprig games?

You will be learning and using JavaScript, and no previous experience with it is required. These are some examples of two games made by beginners:
1. [Lava and Water](https://sprig.hackclub.com/gallery/Lava_and_Water) by Akeel
2. [QuadraPedal](https://sprig.hackclub.com/gallery/QuadraPedal) by Jamarkis

For those of you with more JS experience, designing and building games can stretch and challenge your skills. Check out these games that really push what Sprig can do:
1. [Raycasting](https://sprig.hackclub.com/gallery/raycasting) by Henry
2. [Chess](https://sprig.hackclub.com/gallery/chess) by Thomas

There are hundreds more games in the [Sprig Gallery](https://sprig.hackclub.com/gallery), made by other teenagers, to learn from and take inspiration from!

### Why should I bother with Sprig?
Sprig is an awesome tool to get started in programming! Sprig uses the [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) programming language, which is one of the most popular in the world. By coding games in Sprig, you'll get familiar with the language used to code many of the world's websites, apps, and games. Additionally, many of the concepts you'll learn are applicable to all of programming.

By completing your own game in Sprig, you'll also qualify to receive a [Sprig Console](https://github.com/hackclub/sprig-hardware); it's a DIY kit to make a handheld console, and it can run any Sprig game you build on a computer! 

## 2. Let’s explore the world of Sprig

<video src="https://cloud-qrfzzm21i-hack-club-bot.vercel.app/0untitled.mp4" controls="controls" style={{maxWidth: "720px"}}></video>

This video shows you around the world of sprig.

Start your adventure here https://sprig.hackclub.com/  
From there, check out the gallery of games submitted by teenagers from all over the world. https://sprig.hackclub.com/gallery

Note that you can open any game in the gallery to see its code. In fact, this is a great way to learn coding– see how other hackers solved their game design problems!  
Try clicking on one now!

You’re now in the Sprig code editor! Hitting the RUN button runs the current code, and allows you to play the game.  
Fun hint: the size of your editor and play window can be adjusted.


### Make sure you don't lose your progress

You'll want to register with Sprig to save your work! Otherwise, logging out of your computer could clear your work (this is not fun!!).

In the login page, enter your email. A login code will be sent.

![](https://cloud-2pdfjcqvn-hack-club-bot.vercel.app/0log_in___sprig.png)

Use the code sent to you to log in (can't find it... check spam folders?).

![](https://cloud-hpv87yyem-hack-club-bot.vercel.app/0your_games___sprig.png)

Congrats! You’re now logged in. To access your saved games, use the same email to log in.

## 3. Build Your First Game!
Click on the gallery up top.

![](https://cloud-1f122cf0k-hack-club-bot.vercel.app/0gallery___sprig.png)

We’ll be following the getting_started tutorial. Click it.

![](https://cloud-pcjfwllpn-hack-club-bot.vercel.app/0getting_started___sprig.png)

In the HELP screen there are both a TOOLKIT of functions particular to Sprig, and a TUTORIAL for “Getting_Started.” Follow the instructions there to build your first Sokobon Puzzle!

Click the "remix" button in the top right corner, so that your changes will be saved.

## 4. Wrap-up!
Congratulations! By finishing this session, you just made your first game in Sprig!  

![](https://cloud-4ja9fp00s-hack-club-bot.vercel.app/0image.png)
Next session and for the next 2 sessions, we’ll be building on our knowledge and creating a maze game from scratch. Click [here](/batch/sprig/part-2) to advance to the next session.

Get started making your very first game with the Sprig game engine! Even if you're a beginner, you'll walk out of this jam with your very own game in the Gallery.


Getting familiar with the Sprig Engine + Make your first puzzle!


## (tips for club leaders)
Try to make this club session as collaborative as possible! Collaboration and interaction is what makes meetings fun and keeps people coming back.  
Here's some ideas to encourage this:
- Encourage people to ask the people around them from help as a first resort!
- Have everyone design sprites, then pair up with someone else who creates a story and game around it

## Get Started
Last session, you built a push block game in Sprig (if you haven't, check out [part 1](/batch/sprig/part-1) of this jam!). Let's build off that experience and make something even more awesome!

![](https://cloud-ctbvwlpse-hack-club-bot.vercel.app/0sprig.gif)
*This is a sample of what your base game might look like! I made mine about a watering can who needs to get to a flower, but your game's story, levels, sprites, etc. will be your very own :)*

Today, we'll be learning to make a maze game in Sprig! By the end of this jam, you'll have created your very own maze game from scratch! Next session we'll be adding custom game mechanics and getting ready to share your game with the world! (how exciting is that??)

The tutorial includes hidden hints that you can use if you need. Try your best to work through the challenges using your resources (using the Sprig help, Google, and asking the people around you is all encouraged!) but don't be afraid to use the hints if you need to.

[Click here](https://sprig-nocode.hackclub.dev/maze) for a demo of what you could make today.

Important note: If you’re interested in getting a free Sprig game console for a Game submission, you’ll need to make unique gameplay mechanics beyond the scope of this tutorial (click [here](https://github.com/hackclub/sprig/blob/main/docs/GET_A_SPRIG.md) for the criteria to get a console). We suggest expanding this game to make it more original, or creating a new one once you’ve learned the basics here!

## Brainstorming & sketching
Let's think about how you can make your game unique while following this tutorial! After you take a look at the [demo](https://sprig-nocode.hackclub.dev/maze), take a few minutes with a piece of paper and make some sketches for what your game's characters and objects could look like, what kind of story/theme could be crafted around them, and how you can make your own maze game that is unique to you.

## Starting the tutorial
Let's head to [this page](https://sprig.hackclub.com/gallery/maze_game_starter) and get started with the tutorial! It's in the bottom right corner, just like the getting started tutorial was in session 1. Make sure to click the "Remix" button in the top right corner so your code changes will be saved.

## Wrap-up!
Congratulations!! By finishing this tutorial, you just made your own game from scratch!

![](https://cloud-bsg8pyzmi-hack-club-bot.vercel.app/0screenshot_2023-07-26_at_15.27.47.png)
Next session, we'll be adding custom game mechanics to our game! Take a look at the game mechanics list in [part 3](/batch/sprig/part-3) for some examples of what you can make.

Maze Game (Part 1/3): Characters, Enemies and Maps.


Last session, you built your very own maze game from scratch! (if this isn't true, check out [session 2](/batch/sprig/part-2) of this jam!) Today, we'll be expanding on our game by adding various game mechanics, or features. Take a look at the list of examples below, and make note of what seems fun/interesting/inspiring to you!

This jam should take two one-hour sessions to complete when run in a club.

### List of game mechanics
- Beginning
  - [Keys and locks](https://sprig-nocode.hackclub.dev/maze_keylock)
  - [Pushboxes](https://sprig-nocode.hackclub.dev/maze_pushbox)
  - [Step limit](https://sprig-nocode.hackclub.dev/maze_steps)
  - [Traps](https://sprig-nocode.hackclub.dev/maze_traps)
- Intermediate
  - [Portals](https://sprig-nocode.hackclub.dev/maze_portals)
  - [Fragile tiles](https://sprig-nocode.hackclub.dev/maze_fragile_tiles)
  - [Two player](https://sprig-nocode.hackclub.dev/maze_twoplayers)
- Advanced
  - [Moving obstacles](https://sprig-nocode.hackclub.dev/maze_moving_obstacles)
  - [Sliding movement](https://sprig-nocode.hackclub.dev/maze_jumps)

During these next two sessions, you'll be choosing two game mechanics to implement in your own game! Choose two of varying difficulty levels, and try your best to figure out how to implement them on your own, but don't be afraid to make use of the hints and those around you! Think about how you can combine different game mechanics to play into a cohesive game, and think about how you can build a story around the ones you choose.


## Starting the tutorial
Let's open your game back up from part 2 of this jam (if you haven't done this yet, check out [part 2](/batch/sprig/part-2)!), click the "next" button at the bottom of the tutorial page, and get started with the second part of this game!

## Wrap-up
Great job with finishing this section of the jam and adding some custom game mechanics!

Next session, we'll be polishing our game and making a submission to the Sprig gallery through GitHub.


Maze Game (Part 2/3): Adding Gameplay Mechanics


Congratulations! If you finished the last part of the Jam and implemented two different game mechanics, you've just created an entirely unique game and learned to implement different game mechanics on your own!

I encourage you to keep working on your game - work on making your sprites look great, add some sound effects, and keep working on creating a narrative that tells the story of your characters and why they're trying to solve your maze to get to the goal. What significance does the goal have? What do the individual challenges/game mechanics correspond to?

Once you're done, you can make a PR, or pull request, to add your game to the gallery. It likely won't qualify you to get a free Sprig console (unless you take your game in a truly different direction), but it's still really awesome to finish a game and be able to finally publish it in a gallery that can be seen by everyone.

Follow this link to get started with making a PR! Happy hacking :)  
https://sprig.hackclub.com/get

Maze Game (Part 3/3): Polish & Submit a Pull Request to the Gallery

Make Your First 2D Game with Sprig

Ever have a keyboard, mouse, and more to plug in but only one free USB port to use? You probably fixed it with a USB hub– but how do they work? In this jam you'll build your own from scratch.


_Want to just see the result? See the [Schematic](https://cloud-1we5i4we0-hack-club-bot.vercel.app/1schematic_schematic-usb-hub-2-port-jam_2023-08-10.pdf) and the [EasyEDA source](https://cloud-1we5i4we0-hack-club-bot.vercel.app/0sch_schematic-usb-hub-2-port-jam_2023-08-10.json)._

# Putting the "scheme" in schematic

![](https://cloud-j8bxr01tm-hack-club-bot.vercel.app/1usb_hub_needed.png)

_Has this ever happened to you? You really need a USB hub!_

Today we're going to make a USB splitter. It'll have 1 USB-A on one side, and 2 USB-A ports on the other side. It can transmit power as well as data.

We're starting with a schematic. They're like the blueprint for a PCB. It's a good way to figure out what's connected to what before you actually lay out the parts on your board.

![](https://cloud-6d6aarot8-hack-club-bot.vercel.app/0schematic_to_pcb.png)

> Schematics correspond to the parts of your PCB.

## Start a new project

Go to [EasyEDA](https://easyeda.com/editor) and create a new project (File > New > Project...). Name it `usb-hub`.

## Add the parts

For our design, we're going to need a USB-A connector that plugs into our computer. Click the `Libraries` button on the left toolbar, and search for `C98125`.

![Screenshot 2024-07-14 022430](https://github.com/user-attachments/assets/52e27925-0a72-4a68-a602-4311b9e291ee)

Once you select it, click the `Place` button to add the part to our project. It might look a little different than the images in this tutorial, but that's okay.

![](https://cloud-b1al1d09c-hack-club-bot.vercel.app/00screenshot_2023-08-08_at_12.20.04.png)

Yeah! You did it. Now let's add the other parts we'll need!

We'll need another USB-A connector, but this time a female connector for the devices we charge / plug in. Do another search for `usb-a`. A bunch of options will show up with options like price, stock, and mounting type. You won't understand all the options yet & <b>that's ok</b>! I ended up using part number [`C46407`](https://www.lcsc.com/product-detail/USB-Connectors_Jing-Extension-of-the-Electronic-Co-903-131A1011D10100_C46407.html). This time, place 2 of them on the board.

Next up we need a main board to connect everything together. There are a bunch out there, but I ended up using the CoreChips SL2.1A with part number [`C192893`](https://www.lcsc.com/product-detail/USB-ICs_CoreChips-SL2-1A_C192893.html).

Now that we've got a great big pile of parts in our sandbox, the next step is to connect them together!

## Connect it together

We've got a whole list of parts to hook up now. Let's start with the USB-A male connector to the CoreChips SL2.1A. But what do we need to wire together?

<h2>~~*Connect it together*~~ <ins>Read the spec</ins>!</h2>
<div style={{display: "none"}}>
## Read the spec!
</div>

Let's find the spec for the CoreChips SL2.1A. A spec is kinda like a README for a part. Every part has one, and it's a great place to start when you're trying to figure out how to use a part.

Go to [lcsc.com](https://lcsc.com) and search for `C192893`. Click on the part and scroll down to the `Datasheet` section. Click on the link to download the datasheet.

_Just in case, [here's a link to the spec sheet for the SL2.1A](https://cloud-fa5e1sjdd-hack-club-bot.vercel.app/01811151645_corechips-sl2-1a_c192893.pdf)._

Now let's open it up and just start reading through the table of contents to find where <i>whoops</i> wait it's all in Chinese.

![](https://cloud-961a0s7fx-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_19.05.22.png)

That's fine! Many specs are in other languages and guessing/translating is part of the skill! The important part is in here, the list of pins and what they do. It looks like this:

![](https://cloud-h587v4g5f-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_12.37.30.png)

Printed Circuit Board (PCB) part-makers really like to use acronymns, which are the same in every language! We can use the acronymns to figure out what the pins do. Here's a list of the ones we'll need:

- VDD5: 5V power (also called VCC or VBUS)
- GND: ground
- DP: data positive (also called D+)
- DM: data negative (also called D-)

Great, now we know what we need to do on the chip side, let's find the spec for the USB-A!

The part I chose also had a spec in chinese, but it's a common part so I found [this by googling "USB-A pinout spec"](https://components101.com/connectors/usb-type-a-male-connector). It's a bit different than our pin numbers, but the names are the same. The only difference is that our ports HM1 & HM2 are also `GND` ports. You don't need to know why right now, but for the curious, google "grounded USB shield".

## Connect it together, for real this time!

Move the parts around so they're facing eachother (you can rotate them with the `R` key), the go ahead and connect `GND` on the usb to `GND` on the chip.

![](https://cloud-ntdzh89kj-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_12.48.41.png)

Now you can connect `VCC` on the usb to `VDD5` on the chip. They aren't labelled the same thing, but `VCC` just means a voltage source, and USB-A is a 5V source.

Next up, connect `D+` on the usb to `DP` on the chip, and `D-` on the usb to `DM` on the chip.

![](https://cloud-72qwemi78-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_12.54.13.png)

Hmmmm, this is looking a little like a bowl of spaghetti. Let's clean it up with nets!

![](https://cloud-j8bxr01tm-hack-club-bot.vercel.app/2spaghetti.png)

### Nets

Nets are a way to group together wires that are connected to eachother. They're a great way to make your schematic look cleaner and easier to read. Go ahead and remove the VCC & GND lines, then choose the GND net from the toolbar on the right.

![](https://cloud-m5x117vsl-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_12.56.40.png)

Connect the GND net to the GND pins on the USB-A and the CoreChips SL2.1A. See how clean that new wiring is?

![](https://cloud-7pzslk6qe-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_13.04.24.png)

Nets are kinda like portals– you can connect them from a distance as a way to keep from crossing your wires on your schematic. They're also good for connecting lots of things together– we're going to need to wire a lot of things to `GND` in a sec, and nets are a great way to do that.

Keep in mind though with nets, there are a lot of ways to write things. All the following are a way to say PIN 4 and PIN 5 are connected to `GND`:

![](https://cloud-d47mlqyh7-hack-club-bot.vercel.app/0gnd_net_types.png)

To prevent mistakes, try to keep your nets looking like mine for this tutorial, but in general everyone has their own style and that's ok.

![](https://cloud-j8bxr01tm-hack-club-bot.vercel.app/0gnd_nets.png)

## Ground the Shield

Go ahead and connect MH1 & MH2 to GND also. These aren't really ports- they're just the parts where the metal cover of the USB sticks into the board. We'll connect them to ground in case there's any static electricity.

![](https://cloud-7u8ahczmz-hack-club-bot.vercel.app/0screenshot_2023-10-11_at_13.27.24.png)

![](https://cloud-1vlpmdjo8-hack-club-bot.vercel.app/0screenshot_2023-10-11_at_13.30.41.png)

## Add the other USBs

Next up let's connect the other USB-A connectors!

I'll position my USB-A female ports and hook them up to the main chip's `DP` and `DM` pins. `DP1` goes to USB-1's `D+`. After getting the data lines wired, we'll connect the power using nets!

On these USBs, ports 5 & 6 are the same as ports MH1 & MH2. They're just the metal shield, so we'll connect them to `GND` as well.

![](https://cloud-6cwv1d324-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_15.16.16.png)

_Remember, with nets you can connect from a distance!_

## Power surges

The design is almost complete, and in a perfect world it would work just fine. But we aren't in a perfect world- we live in a world with static electricty and power surges. We'll need to now protect our circuit. If we don't, we could fry our hub or even our computer's USB port!

Knowing where these protective components go can be an art and hotly debated on many stackoverflow forms. Fortunately, the spec sheets we're using contain some example circuits for us to use. Let's take a look at the CoreChips SL2.1A spec sheet again:

![](https://cloud-a1u1u3jnb-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_17.32.45.png)

_This is a little hard to see, so we'll go through it step by step. For now, just know we're getting the following instructions from reading this image & adapting it a little for our own design._

First up we'll add a diode to protect from a surge coming _from the laptop_. That's a case where the laptop sends too much power and goes beyond the 5V we want. The Schottky (pronounced "shot-key") diode with part number [`C48192`](https://www.lcsc.com/product-detail/Schottky-Barrier-Diodes-SBD_onsemi-NSR0320MW2T1G_C48192.html) is perfect for this. Let's drop it in right after we take on the 5V power from the USB-A male.

_Diodes ensure power flows in 1 direction. We don't want an accidental spike to flow back into our laptop! This Schottky diode will also slightly resist the flow of electricity, which is good for protecting against power surges._

Now let's protect from power surges that make it past the diode. We'll use a capacitor for this– it's kinda like a resevior for power. It can store up power and then release it when it's needed. If there's a power fluctuation, this capacitor will let the extra power blead out to `GND` harmlessly. We'll use a 10uF capacitor with part number [`C19702`](https://www.lcsc.com/product-detail/Multilayer-Ceramic-Capacitors-MLCC-SMD-SMT_Samsung-Electro-Mechanics-CL10A106KP8NNNC_C19702.html). Let's drop it in right after the diode, and connect it to `GND`.

![](https://cloud-e0ekzo8gw-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_17.37.55.png)

_When using a capacitor to prevent overflows like this it's called a ["decoupling capacitor"](https://components101.com/articles/decoupling-capacitor-vs-bypass-capacitors-working-and-applications). I'll admit I don't 100% understand why, but this won't short 5V to GND._

Go ahead and use the same capacitors to protect the other USB-A ports. You can copy & paste the components, and then move them into place.

![](https://cloud-lr6vmvrrj-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_17.44.21.png)

## Unused ports

The SL2.1A chip we're using supports up to 4 USB ports, but we're making a smaller board for the tutorial so we won't be using the ports for "3" or "4". Go ahead and use the "no connection" tool to show in the schematic that these pins aren't being used.

_Making a 4-port USB hub is left as a challenge for you to do if you want to!_

![](https://cloud-4sab6gwqz-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_17.51.45.png)

All finished should have pins connected to some label or wire, even if it's just a "no connection" symbol. Your PCB will error if you try to send it to the manufacturer with any pins unlabeled.

![](https://cloud-me27qfpwb-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_17.51.54.png)

Next up are pins `VDD33` and `VDD18`. Sometimes components will have these to provide lower voltages for their internal circuitry. We don't need to worry about them for this design, but the spec shows that we need to bleed off the power to `GND` using another 10uF capacitor.

![](https://cloud-p9cf2w5jg-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_17.58.13.png)

Lastly, our chip provides clock circuitry through `XIN` and `XOUT` for advanced use if we wanted to overclock our USB ports. We aren't trying to do that, so we'll opt-out of it by connecting `XIN` to `GND` and marking `XOUT` as disconnected.

![](https://cloud-np517gxwl-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_18.02.06.png)

Now, let's check if all the pins are connected. Try converting the schematic to a PCB. If you see a warning pop up that means a net is missing or not connected. ![](https://cloud-dmskkj3bl-hack-club-bot.vercel.app/0screenshot_2023-08-08_at_18.36.08.png)

## Finished!

If all the schematic is connected you've done it!

![](https://cloud-4dr6xa7qz-hack-club-bot.vercel.app/0yay.gif)

   <Announcement
            copy="Now make your board"
            caption="Take your board and build a working USB hub."
            href="/batch/usb-hub/part-2"
            iconLeft="enter"
            color="primary"
          />

Now let's move into the PCB editor to make our board.


Get started making your schematic for your very own USB hub! Even if you're a beginner, you'll walk out of this jam with your very own schematic.


Get familiar with PCBs + Make a blueprint!


_If you haven't built a schematic yet, do so in [part 1](/batch/usb-hub/part-1). Just in case you can start with the [Schematic](https://cloud-1we5i4we0-hack-club-bot.vercel.app/1schematic_schematic-usb-hub-2-port-jam_2023-08-10.pdf) and the [EasyEDA source](https://cloud-1we5i4we0-hack-club-bot.vercel.app/0sch_schematic-usb-hub-2-port-jam_2023-08-10.json) we're starting with. Want to see the final result of this project? Here's a link to the final [EasyEDA Design](https://example.com)_

# Building the board!

Now that we have our schematic, let's turn it into a board!

Our starting schematic should look like this: ![](https://cloud-dtcbpm4i4-hack-club-bot.vercel.app/2screenshot_2023-08-11_at_12.52.40.png)

This is what we're going to make: ![](https://cloud-dtcbpm4i4-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_13.11.34.png)

Once it's ordered, it'll look like this: ![](https://cloud-dtcbpm4i4-hack-club-bot.vercel.app/1screenshot_2023-08-11_at_13.11.20.png)

## Step 1: Convert the schematic to a board

Click "Design > Convert to PCB" in the top right corner of EasyEDA. This will open up the board editor.

![](https://cloud-6cbfcd1xm-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_13.15.22.png)

Next, confirm all the settings are exactly the same as– JK! these settings don't matter, just hit "apply" and move on:

![](https://cloud-8ie7yt1k6-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_13.14.34.png)

We'll be confronted with our parts laying out in the editor kinda like when we started out with the schematic. We'll need to move them around to make them fit on the board.

![](https://cloud-8ie7yt1k6-hack-club-bot.vercel.app/1screenshot_2023-08-11_at_13.14.44.png)

## Step 2: Move the parts around

We want our parts to be generally close to what they should be connected to before connecting everything all together. This will make it easier to route the traces (fancy phrase for "wire it all up") later.

We've got a handy little tool to help us figure out our positions though! Rat lines! These are the little blue lines that connect the pins of our parts together. We can use these to figure out where to put our parts.

_This is generated from our schematic, and is why we built our schematic first! If one of the blue lines ends up looking wrong it's usually because we're missing something in our schematics._

I moved the parts around a bit and ended up with this. A few things still overlap, but for the most part the lines have a clear route:

![](https://cloud-5c3t0a3re-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_13.20.04.png)

_Keep in mind you might need to rotate your parts. Go ahead and do it with the "R" key. You can also rotate by degrees in the "Rotation" field on the right toolbar._

## Step 3: Route the traces (wire up the dots)

Next up comes the fun part! Let's wire up our parts. This is more of an art than a science, but I recommend a couple tips:

- Do `GND` last. It's very important, but the easiest to do.
- You don't have to finish everything in one go. It usually takes a couple passes to get everything right & you'll end up with a better design if you don't force it all in one go.
- Don't be afraid to move your parts around if you need to.

First I'll select the "Track" tool on the toolbar:

![](https://cloud-ikeoztttt-hack-club-bot.vercel.app/1screenshot_2023-08-11_at_13.26.54.png)

I'm starting with the +5V trace in this example:

![](https://cloud-ikeoztttt-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_13.27.39.png)

Lastly, this wire is a little thin for us, so let's <b>embiggen</b> it. Too small and the wire might burn out, but too big and it's hard to fit all your wires. There are a whole set of tables online that you can use to figure out the right width, but I usually just go with 0.8mm for my traces at +5V.

![](https://cloud-ikeoztttt-hack-club-bot.vercel.app/2screenshot_2023-08-11_at_13.27.10.png)

![](https://cloud-2dgv2s40z-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_13.31.56.png)

_Technically, you can add an extra "c" to "thicc" for every 0.4mm of width._

Take your time and route the traces you can. Here's how far I got after a couple passes:

![](https://cloud-l9gg41b78-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_13.38.20.png)

Notice that the +5V traces are still ratlined. I couldn't connect them without overlapping other traces, so I've left them unrouted for now. There's also part of the `GND` line that isn't connected yet.

## Step 4: Oh, how the turn tables!

Now we need more space to route our stuff! Let's break out our superpower– the other side of the board!

![](https://cloud-559tio290-hack-club-bot.vercel.app/0ezgif.com-video-to-gif_1_.gif)

That's right- the other side of the board can have a trace too! Some boards are pancaked together and have 4, 6, even 16 layers of traces! We're not going to be that fancy with this though– we can get away with just 2 layers for this project. Good for simplicity and keeping our costs down.

Let's use this tool to route the `D-` (for some reason showing up as `U3_9` in my screenshot) pin for the USB-A male.

![](https://cloud-2421gzzt3-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_13.48.30.png)

Add some traces to get the `U3_9` line as close as it can without overlapping anything.

![](https://cloud-p4gld99aq-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_13.50.20.png)

Switch to the "Via" tool and click the tip of the traces to add them to the tips. A "Via" is just a fancy way to say we're poking a whole through the board to the other side that's coated in copper so the current travels through it.

![](https://cloud-loxykkofo-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_13.50.39.png)

![](https://cloud-cbdjno25j-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_13.51.55.png)

To switch to the other side of the board, click the "edit" icon next to "BottomLayer" on the layer toolbar. It should look like a pencil

![](https://cloud-n59r7hpq4-hack-club-bot.vercel.app/1screenshot_2023-08-11_at_13.46.16.png)

Now we can route our traces on the bottom layer. Go ahead and connect the 2 vias we just made:

![](https://cloud-8juvc3e6w-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_13.56.55.png)

Nice! Now the ratline has disappeared- that means we're all done with those pins!

Try doing the rest of them on your own before continuing. Or don't... I'm just text on a website, I can't stop you from scrolling down to see the finished version.

![](https://cloud-isdsylawg-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_14.00.12.png)
![](https://cloud-isdsylawg-hack-club-bot.vercel.app/1screenshot_2023-08-11_at_14.00.24.png)

_I had to add some more traces on the "TopLayer" to get all my "BackLayer" pins to connect._

## Step 5: Cut that out!

Next up we'll need to cut out our board and give it a shape! We'll use the "BoardOutline" layer to do this. Weirdly enough, we'll still be using the route tool like before.

![](https://cloud-pxqhij3q1-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_14.02.31.png)

_You might already have a pink rectangle lying around from when you first imported your board from your schematic. Go ahead and delete that, we're making our own outline. A better outline!_

![](https://cloud-dmke8w78v-hack-club-bot.vercel.app/1screenshot_2023-08-11_at_14.06.12.png)


If your male USB port has a pink line in the footprint, make sure it's **outside** of the board outline. Some USB ports are "sink components," which means that they go below the board. This makes sure to give them ample room.

![](https://github.com/user-attachments/assets/ab60dfac-8d52-4314-9388-d7945c2770b0)
![](https://github.com/user-attachments/assets/d746092d-cd29-41b9-9dc7-de4a335959eb)



I made my trace look like this, but yours can look different! Just make sure that it's a closed shape and has enough padding around the edges that we don't trim of anything important. Sometimes the cutting machine will be a little off, so it's good to have a little extra space on the sides.

Also, don't forget to even out your corners!

![](https://cloud-dmke8w78v-hack-club-bot.vercel.app/0ezgif.com-video-to-gif_2_.gif)

Now that we have the borders cut out, let's see the results! Click "View > 3D View" in the top toolbar.

![](https://cloud-kcfrggbze-hack-club-bot.vercel.app/0screenshot_2023-08-11_at_14.10.51.png)

![](https://cloud-kcfrggbze-hack-club-bot.vercel.app/1screenshot_2023-08-11_at_14.11.06.png)

Done! That's it. You don't have to go home, but you can't stay here.


Use a schematic to start building your own USB hub!


Turn your blueprint into a board and order it!

Build a USB Hub


Imagine a world where you have the power to shape the landscape and design your dream buildings. **Today, we'll dive into the fundamentals of 3D modeling by building our own sky islands and collaborate by merging them into a community sky village.**

Here's an example of what you'll be able to make:
![Individual demo](https://cloud-b1g9hwiu1-hack-club-bot.vercel.app/0image.png)
[Demo](https://app.spline.design/file/dd7decef-bf50-4ca5-bff5-d76ba64513c4)

And... here's an example of a sky village if you put multiple islands together!
![Group collab demo](https://cloud-8oi5u7dkg-hack-club-bot.vercel.app/0image.png)
[Demo](https://app.spline.design/file/652cf287-958a-4b01-a818-b6a09868f645)

So without further ado, let's get started!

## Getting started with Spline
1. Head over to [spline.design](https://spline.design) and create an account. Select "New File" to get started.
![Getting started - Step 1](https://cloud-cmkhxafch-hack-club-bot.vercel.app/1gettingstarted-1.png)

2. Play around with the UI and controls!
![Getting started - Step 2](https://cloud-cmkhxafch-hack-club-bot.vercel.app/0gettingstarted-2.png)
**Toolbar:** Add shapes, select/view modes, and edit tools.
- Press “+” for more tools and objects to add to the scene.
- Press “▷” to access Play mode.  
**Left sidebar:** objects and layers in the scene.  
**Right sidebar:** property panels. Change properties of objects or the scene.

## Important controls 🕹️
<Grid cols={3}>
<GridItem>
**Orbit:** `alt`/`⌥` + `drag`
</GridItem>
<GridItem>
**Zoom:** `scroll`
</GridItem>
<GridItem>
**Pan:** `space` + `drag` OR `scroll wheel drag`
</GridItem>
</Grid>

## Creating your island 🏝️
Start thinking about what you want on your own island: your dream mansion on a mountaintop, a treehouse in the forest, an amusement park—the sky’s the limit!

> We’re going to start by building a basic house. Afterwards, you can transform it to make it your own!

<Dropdown title="1. Let's start by adding the ground.">
<Grid cols={2}>
<GridItem>
![Creating your island - Step 1A](https://cloud-3klicbvir-hack-club-bot.vercel.app/9creatingisland-1a.gif)
</GridItem>
<GridItem>
Select (single-click) the square.
Rotate the square flat and change the size to 500x500.
- Rotation: X90
- Size: X500, Y500
</GridItem>

<GridItem>
![Creating your island - Step 1B](https://cloud-3klicbvir-hack-club-bot.vercel.app/8creatingisland-1b.gif)
</GridItem>
<GridItem>
Select (single-click) the square.
Extrude the square by 50 and add some roundness.
- Extrusion: 50
- Corner: 100
- Bevel: 16
- Bevel Sides: 6

<Comment githubUser="linkai101">
Keep in mind that you can always change these settings anytime as you add more structures and decorations!
</Comment>
</GridItem>
</Grid>
</Dropdown>

<Dropdown title="2. Create the base house model.">
<Grid cols={2}>
<GridItem>
![Creating your island - Step 2A](https://cloud-3klicbvir-hack-club-bot.vercel.app/7creatingisland-2a.gif)
</GridItem>
<GridItem>
> We’ll start with the body of the house.

Press “+” in the toolbar, then “Cube”. Select the top of the base so it highlights red.
Adjust settings:
- Size: X200, Y200, Z200
- Corner: 0
- Position: X0, Y150, Z0
</GridItem>

<GridItem>
![Creating your island - Step 2B](https://cloud-3klicbvir-hack-club-bot.vercel.app/6creatingisland-2b.gif)
</GridItem>
<GridItem>
Select (single-click) the cube. Adjust settings:
- Click “Smooth & Edit”
- Subdivision Modifier > Level: 0

<Comment githubUser="linkai101">
**Editing mode** is accessed when double-clicking on an object. This allows you to modify vertices, edges, faces, and more! Getting the hang of it?
</Comment>

Double-click the cube.
In the toolbar, select the `Loop Cut (C)` tool. Make a vertical subdivision.
In the toolbar, select the `Vertex (V)` select tool.
- Select the 4 vertices of the top face (shift + drag)
- Drag the vertices down to form an angled roof shape.
</GridItem>

<GridItem>
![Creating your island - Step 2C](https://cloud-3klicbvir-hack-club-bot.vercel.app/5creatingisland-2c.gif)
</GridItem>
<GridItem>
> Now, let’s make the roof.

Duplicate the cube and drag the copy up.
- `Ctrl`/`⌘`+`D` OR right-click > Duplicate

In the toolbar, select the `Vertex (V)` select tool.

- Arrange the vertices to form a roof.  
Exit (”X”) out and drag the roof down. Repeat the above steps until the roof sits flush on the house.
</GridItem>

<GridItem>
![Creating your island - Step 2D](https://cloud-3klicbvir-hack-club-bot.vercel.app/4creatingisland-2d.gif)
</GridItem>
<GridItem>
> Let’s add some roundness to the roof.

Select (single-click) the roof. Adjust settings:
- Subdivision Modifier > Level: 2
In the toolbar, select the `Loop Cut (C)` tool.
- Add subdivisions throughout to shape the roof.

<Comment githubUser="linkai101">
**Subdivisions** act as anchors in the shape for where the edges get rounded. Add and move the subdivisions to see how they affect the rounding!
</Comment>
</GridItem>

<GridItem>
![Creating your island - Step 2E](https://cloud-3klicbvir-hack-club-bot.vercel.app/3creatingisland-2e.gif)
</GridItem>
<GridItem>
> Now some roundness for the walls.

Repeat the above steps on the body.
</GridItem>
</Grid>
</Dropdown>

<Dropdown title="3. Add colors!">
<Grid cols={2}>
<GridItem>
![Creating your island - Step 3A](https://cloud-3klicbvir-hack-club-bot.vercel.app/2creatingisland-3a.gif)
</GridItem>
<GridItem>
> Our scene desperately needs a makeover. Let’s start with the background!

Click the background to deselect all objects. Adjust scene settings:
- Frame > BG Color: any color you want!
</GridItem>

<GridItem>
![Creating your island - Step 3B](https://cloud-3klicbvir-hack-club-bot.vercel.app/1creatingisland-3b.gif)
</GridItem>
<GridItem>
<Comment githubUser="linkai101">
The **Depth** material type creates a gradient of color along an axis. In "Ramp", you can adjust and add the color stops. Try it out!
</Comment>

> Now, let’s make the ground look like grass and dirt.

Select (single-click) the ground. Adjust settings:
- Material > <strike>Color</strike> Depth
- Type: Linear
- Direction: X0 Y0 Z1

Adjust the start and end positions of the depth layer.
In “Ramp”, select colors for dirt and grass and adjust their positions.
</GridItem>

<GridItem>
![Creating your island - Step 3C](https://cloud-3klicbvir-hack-club-bot.vercel.app/0creatingisland-3c.gif)
</GridItem>
<GridItem>
Repeat for the walls and the roof. Make it your own!
</GridItem>
</Grid>
</Dropdown>

<Dropdown title="4. Add doors, windows, and doorknobs.">
<Grid cols={2}>
<GridItem>
![Creating your island - Step 4](https://cloud-kv6txjh6s-hack-club-bot.vercel.app/4creatingisland-4.png)
</GridItem>
<GridItem>
> You’re on your own for this one. You got this!

In the toolbar, use the `Rectangle (R)` and `Ellipse (O)` tools to draw doors and windows on the house.
Add rounding and color to them as well.
> 💡 **Hint:** To add rounding to specific corners, click the "⛶” icon in Shape > Corner.
</GridItem>
</Grid>
</Dropdown>

<Dropdown title="5. Add trees.">
<Grid cols={2}>
<GridItem>
![Creating your island - Step 5](https://cloud-kv6txjh6s-hack-club-bot.vercel.app/3creatingisland-5.png)
</GridItem>
<GridItem>
> You’re on your own for this one. You got this!

In the toolbar, add cubes and cylinders with the “+” icon to form trees.
Add rounding and color to them as well. Try using a Depth material for a gradient effect.
</GridItem>
</Grid>
</Dropdown>

<Dropdown title="6. Add shadows influenced by surrounding color.">
<Grid cols={2}>
<GridItem>
![Creating your island - Step 6](https://cloud-kv6txjh6s-hack-club-bot.vercel.app/2creatingisland-6.gif)
</GridItem>
<GridItem>
> Let’s add a green glow effect coming from the trees!

<Comment githubUser="linkai101">
Materials can consist of multiple layers! See how the **Depth** layer adds a green glow to the house illuminating the tree.
</Comment>

Select (left-click) the body of the house. In Material:
- Click the “+” icon to add a new layer.
- Select <strike>Color</strike> Depth

Drag the origin of the layer to the tree and adjust the end position.
- In “Ramp”, set the left slider to the tree color and the right slider to white.
- Click the icon in “Depth” that looks like two overlapping circles, and select “Multiply”

> Repeat this for the other tree.
</GridItem>
</Grid>
</Dropdown>

<Dropdown title="7. Build a stone path to the door.">
<Grid cols={2}>
<GridItem>
![Creating your island - Step 7](https://cloud-kv6txjh6s-hack-club-bot.vercel.app/1creatingisland-7.gif)
</GridItem>
<GridItem>
> Let’s build a stone path toward the door!

In the toolbar, select the `Vector` tool. Draw the vertices to form a stone step. Adjust settings:
- Corner: 8
- Extrusion: 2
- Position: Y50
- Bevel: 1
- Material > Color: any color you want!
> Repeat this for the rest of the stones in the path.
</GridItem>
</Grid>
</Dropdown>

## Optional activity: making assets! 📦
If you're working in a group and have extra time, this could be really fun to spice up the collaboration: making custom assets to use in each of your islands!
### The Task
Each person will create a single asset from scratch—it could be anything from a funny-looking lawn chair to a giant Among Us crewmate statue! The assets that everyone makes will be available for others to use to customize their islands in the following steps.

## Customizing your island 🎀
Now you know the basics of Spline, **it's time to start making the island your own**. Transform this basic house into your dream mansion, expand your island with more structures, or start from scratch to build something unique!

> Here are some ideas for what to make:
> - A park
> - A town in the wild west
> - Your dream house or resort
> - A space station
> - Recreate a building from your favorite movie or video game
> - Your school/the building you’re currently in

### Spline’s asset library
Spline has a ***huge*** library of 3D models and scenes for you to use in your project! Sprinkle little details into your island or add full building prefabs to form towns and parks.

![Spline's asset library](https://cloud-kv6txjh6s-hack-club-bot.vercel.app/0splinelibrary.png)

## Build a collaborative sky village by linking islands 🌉
Collaboration is one of the most fun and fulfilling aspects of design and making, and Spline makes it super easy! If you're working with a group or wanna collab with a few friends, let's build a sky village!

<Comment githubUser="linkai101">
Note: Spline's free tier currently only has 2 additional editor seats. (file owner + 2 other editors) You could still make it work if everyone sends their islands to the leader(s) who links them together.
</Comment>

1. Have the club/group leader create a new file on Spline. Share the file with the rest of the group with editing privileges.
![Linking islands - Step 1](https://cloud-mn9anfpic-hack-club-bot.vercel.app/0image.png)

2. Copy and paste each island into this master file. Connect them with bridges in the asset library or find your own creative way to link the islands!
![Group collab demo](https://cloud-8oi5u7dkg-hack-club-bot.vercel.app/0image.png)

## What's next 🔮
3D modeling literally has limitless possibilities. Here are a few:
- Visualize and manipulate 3D models in HTML with [three.js](https://threejs.org/)
- 3D printing and inventing
- Use them in Unity, Unreal Engine, or other 3D game development applications
- Augmented/visual reality (AR/VR)
- Just for fun or for the sake of art—create and showcase a portfolio!

I wonder what you'll build next with 3D! 😁

### Exporting
Often in big projects like making 3D games and websites, 3D modeling is only one side of the story. You'll eventually need to export them into another app, and here's how you do it:

<Comment githubUser="linkai101">
Keep in mind that some export options are only available to the paid tiers. 😐 You should be able to get by though!
</Comment>

1. In the toolbar, click on "Export". There will be options on the left-hand side for various file formats to export to.
![Exporting](https://cloud-ctimzr33x-hack-club-bot.vercel.app/0image.png)

### Jams to do next
> Looking for more 3D jams? I gotchu!

**[Mastering the Matrix: Crafting Your Own Web-based AR App](/jam/web-ar)**  
Deploy your 3D models into the metaverse! Learn how to make a web-based AR app in which you can display and manipulate your 3D models from Spline.

**[Crafting Weapons, Shields, and Armor in TinkerCAD](/batch/3d-armory)**  
TinkerCAD is a great web-based beginner CAD software. Computer-aided design (CAD) is often used for designing 3D models for engineering purposes!

In this jam, you'll create your very own virtual sky village with Spline, a web-based 3D modeling software.


Build your own 3D club village


Hey there 👋

If you've ever wanted to make your own immersive and expansive 3D worlds, you've come to the right spot. Imagine big forests, huge deserts, all the things in your imagination coming to life.

**Outline:**
1. Setting up Replit
2. What's A-Frame?
3. Adding A-Frame
4. Creating a scene
5. Adding elements
6. Attributes
7. Customization
8. Deploying your site
9. Getting a free Frappuccino
10. Wrapping up
## Setting up Replit 
Go to [https://replit.com](https://replit.com) and create/log into an account:
![Replit authentication page](https://cloud-99ig98peo-hack-club-bot.vercel.app/0image.png)

Then, go ahead and create a project by going to "Create Repl" on the sidebar > selecting HTML, CSS, JS > giving it a title > hitting "Create Repl"

![Creating HTML CSS JS Repl](https://cloud-p82fpfgs2-hack-club-bot.vercel.app/0outputgif.gif)

## What's A-Frame?

![aframe logo](https://cloud-m5c3nxgbo-hack-club-bot.vercel.app/0image.png)

Building 3D worlds used to be pretty hard to approach due to its high learning curve. A-Frame is a library to help make this stuff MUCH easier. Instead of getting lost in the weeds, it provides a simple interface for you to create 3D websites.

Here are some of the amazing things people have made with A-Frame:
1. [A-Blast](https://aframe.io/a-blast/)
![a-blast ui](https://cloud-3j84pfit2-hack-club-bot.vercel.app/0image.png)
2. [Access Mars](https://accessmars.withgoogle.com/)
![access mars preview](https://cloud-grr8upimy-hack-club-bot.vercel.app/0image.png)
3. [Moonrider](https://moonrider.xyz/)
![moonrider ui](https://cloud-rcqx7la5t-hack-club-bot.vercel.app/0image.png)

## Adding A-Frame

Hey, do you notice the `<head>` tag in our HTML? Yeah, we can add a script via the  `<script>` tag to give our website A-Frame's superpowers! Put this within the `<head>`

```js
<script src="https://aframe.io/releases/1.6.0/aframe.min.js"></script>
```
![instructions of putting script within head tag](https://cloud-byterps5u-hack-club-bot.vercel.app/0image.png)

## Creating a scene

To actually use A-Frame, we need to create a scene to add elements. We can do so with the `<a-scene>` tag

Remove the "Hello world" text within the `<body>` tags and add:

```html
<a-scene>
</a-scene>
```

All of our elements will go here. What are these elements you might ask?
## Adding elements

A-Frame has different tags for different 3D elements. For example, you can use `<a-box>` to create a cube, and `<a-sphere>` to create a ball.

Here are all the different kinds of elements (use `<a-[ELEMENT-NAME]>` to use these):
![showcase of all a-frame tags](https://cloud-69ehuc8ev-hack-club-bot.vercel.app/0image.png)

![visual map of entities in a scene](https://cloud-mgilf4sx7-hack-club-bot.vercel.app/0image.png)

Within your `<a-scene>`, add a box:

```html
<a-scene>
	<a-box></a-box>
</a-scene>
```

Click on the panel on the right and use your WASD keys + mouse to move around. You should see a box after you move around (click the run button at the top of the page if nothing shows up):
![demo of white box ](https://cloud-klvbtj50y-hack-club-bot.vercel.app/0screen_recording_june_17.gif)

Hmm, we should probably have some color. After all, things are much better with colors!

To do this you can add the `color` attribute to `<a-box>`! For example, you can do `<a-box color="blue"></a-box>` to get a blue cube.

Choose any color you want, you can put a [CSS color keyword](https://www.w3.org/wiki/CSS/Properties/color/keywords) or a hex code (like `#000`) as a color. 

## Attributes

There are lots of attributes (A-Frame calls them components) that you can add to your objects. For example, there is the `position` attribute that allows you to put your object in a certain position in space (e.g. `position="1 0 3"` correlates to the x, y, and z positions respectively).

Experiment with these attributes (Google for more!) and build something amazing.

Some example props you can play around with are:
1. `animation`: animates the objects (you can use these to move your object)
2. `rotation`: rotate your object, allows for fun designs

## Customization

While you probably just have a cube right now, you can add so much more!

Want to add physics? There's [a library](https://github.com/c-frame/aframe-physics-system/blob/master/CannonDriver.md#installation) for that. Want to create a cool environment? Check out [this](https://github.com/supermedium/aframe-environment-component) environment component!

The possibilities are truly endless with A-Frame, and it's super easy to share your site as well!

## Deploying your site

It's really simple to deploy your site. Go to https://netlify.app and create an account.

After doing so, go to Replit and download your files as a `.zip` file. You can do this by clicking the three dots above all your files and clicking "Download as ZIP":

![image of ui to download as zip](https://cloud-ecgsox4ue-hack-club-bot.vercel.app/0image.png)

After this, go to https://app.netlify.com/drop and drag and drop your `.zip` file there.

After it uploads, click "Open production deploy" to see your live site!

![image of opening deploy](https://cloud-bpr687t0e-hack-club-bot.vercel.app/0image.png)

## Getting a free frappuccino

You've put so much effort into getting your site up and running—we think you deserve a little treat after all that. Head over to https://github.com/hackclub/hackaccino, submit your pull request for review, and get a free Frappuccino!


![frap spinning gif](https://media0.giphy.com/media/v1.Y2lkPTc5MGI3NjExM3B3M2xkM3FyczZhY2lrdzkxd3dycHA5Mzc0MW1laHF6Nzh1MGNhZCZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/2FazplK2PyGh3Rjby/giphy.webp)

## Wrapping up
Awesome work on this site! To wrap up, we suggest sharing your site in our [Slack](https://hackclub.com/slack), it's where a bunch of cool teen coders are shipping projects daily and having fun with projects like these! Head over to the `#ship` channel and post about your project!

Here's some cool stuff that Hack Clubbers have made:

1. [Adrian De Gendt](https://github.com/Space1415/) made an amazing [solar system model](https://subsequent-thoughtful-tarantula.glitch.me/) 
![solar system example from adrian de gendt](https://cloud-1e2jtrqm9-hack-club-bot.vercel.app/0image.png)

2. [Aayan Rahman](https://github.com/aayanrahman/) made [Bloxy](https://aayanrahman.github.io/HackaccinoGrant.github.io/), a block-game demo inspired by Minecraft 
![bloxy demo](https://cloud-c2fzf76vl-hack-club-bot.vercel.app/0image.png)

3. [Dieter Schoening](https://github.com/Deetschoe) made [Aurality](https://aurality.vercel.app/), a webapp that displays your Spotify top songs in 3D!
![aurality demo](https://cloud-a5dhhs37l-hack-club-bot.vercel.app/0image.png)

So there you have it, go out and create great things with the tools and skills you have.

— Shubham Patil


Making 3D Worlds in HTML

This Jam will teach you how to use ChatGPT and AI to create a trip itinerary planner. It is extremely customizable and gives a foundation for you to expand upon with your own ideas!


Make an AI Trip Planner for a Club Adventure


Contributors: [@wollygfx](https://github.com/wollygfx "View @wollygfx on GitHub")
Edited by: [@zsh](https://read.cv/zoyashussain)
Time: 45-50 minutes, Beginner 
****
> It's time to start modelling! In this Jam, we'll be developing 3D models with the JavaScript library [Zdog](https://zzz.dog/#made-with-zdog). You ready? Let's go!

## Outline:
1. **Goal-setting**: Explore what we'll be doing in this workshop, and examples of 3D models _you (yes,_ you!) can create.
2. **Set-Up**: Follow as we walk through the steps of setting up your coding environment to write code in HTML and JS.
3. **HTML Part**: Write the HTML to prepare for creating models in JS.
4. **JS Part**: Learn how to create shapes with Zdog and JS with a combination of code, mathematics, and art 👀
5. **Additional Challenges**: Once you've nailed down the basics of 3D modeling with JS, check out some challenges to spice up your project 🌶️

At the end of this workshop, you will be able to make 3D models like these:
![examples](https://cloud-5a0ya05fk.vercel.app/0large.gif)

Here's a [live demo](https://repl.it/@wollygfx/Hack-Club-logo) of what we will make, you can also find the final code there.

![Hack Club 3D logo](https://cloud-590c1rr82.vercel.app/0screen_recording_2020-10-21_at_7.00.53_am.gif)

## Set Up
This workshop requires a very basic knowledge of the following languages: HTML & JS. Don’t worry if you get stuck at some point in the workshop, everything is explained the best way for you to understand!

For this workshop we will use [Repl.it](https://repl.it), click [here](https://repl.it/languages/html) to create a coding environment right for this workshop.

![Setup](https://cloud-qbmylslty.vercel.app/0image.png)

## HTML part

Awesome, now you've got everything set up to begin coding! Now, let's begin with HTML.

First, we want to create inside of the `<body>` tag a `<canvas>` in which, the 3D model we are going to create will render. Then, put a class; feel free to name it as however you want to… I will name it with the class `model`.

```html
<canvas class="model"></canvas>
```

Now we have to put the following code inside of the `<body>` tag, this code allows us to use the Zdog library without having to download it. Learn about CDN [here](https://en.wikipedia.org/wiki/Content_delivery_network).

```html
<script src="https://unpkg.com/zdog@1/dist/zdog.dist.min.js"></script>
```

In the end, your code should look something like this:

```html
<body>
  <canvas class="model"></canvas>
  <script src="https://unpkg.com/zdog@1/dist/zdog.dist.min.js"></script>
  <script src="script.js"></script>
</body>
```

_Note: It’s very important to keep this order to make sure everything works perfectly_

## JS part
Now that we have our HTML file ready to go, we gotta work on our JavaScript file.

![Cool gif](https://cloud-p49mi1lgl.vercel.app/0tumblr_e49d74c805eec46704d22c1da59ecded_cc93a056_500.gif)

### Setting up the canvas
We are going to start with the fun part. First, let’s create the main variable and let’s give it a name. Feel free to give your variables [any name](https://sentry.io/answers/naming-variables-in-javascript/). For this tutorial, I'll use “ws”.

```javascript
const ws = new Zdog.Illustration({
  element: '.model',
  resize: 'fullscreen',
})
```

Let's break this down:
1. **Illustration** is the top-level class that handles dealing with the `<canvas>` element, holding all the shapes in the scene, and displaying those shapes in the element
2. **element** we use this element to match the render with the canvas tag
3. **resize** is used to modify the size in which the model will be rendered, in this case, the 3D model will render on the whole screen. If you want to, you can remove this element

At this point nothing shows up yet, so let’s create our first 3D model. 

### Creating the model
Now, we’re gonna create a shape, for this workshop I want to make a simple cube, but you can create whatever you want to. Here is a list of [shapes](https://zzz.dog/shapes) you can create with Zdog.

_Note: Every shape has its own properties or elements, you can check [the full list here](https://zzz.dog/shapes)._

Let’s add the following code to our JS file:

```javascript
new Zdog.Box({
  addTo: ws,
  width: 100,
  height: 100,
  depth: 100,
  stroke: false,
  leftFace: '#da0',
  rightFace: '#e62',
  topFace: '#ed0',
  bottomFace: '#636',
})
```

Explanation:
1. Box is a shape class, you can replace this for the shape you want to use…
2. We made the 3D model (cube) a child to the main Zdog Illustration (ws) using the addTo element. This element must be there, otherwise the 3D model will not render.
3. The width, height and depth elements can either stretch or shrink the shape of your box:
    - Width: Sets the width of the cube
    - Height: Sets the height of the cube
    - Depth: Sets the depth of the cube. If the value is 0, the cube will render as a 2d square; so make sure to give it a value.

4. The Stroke element gives the 3D model a stroke, it works as an external layer that you can use to give your 3D model a rounded look. Play around with it!
5. leftFace, rightFace, topFace & bottomFace elements give color to each face of the 3D model, try using different colors for each face, so that you can appreciate way better the animations you make.

### Rendering
Now that we have created our 3D model, let’s render it. Use the following line of code to render the cube we just created.

```javascript
ws.updateRenderGraph()
```

This code updates and render your Zdog illustration that was declared in the first variable, so make sure to write the correct name in.

Now let's click on the **Run** button to see what happens…

![Render image](https://cloud-k11ck8g2n.vercel.app/0image.png)

Congrats, you just made your first 3D model… Yeah, maybe not what you were expecting. Let’s fix this by animating it.

![woah gif](https://cloud-kr2lyxjbx.vercel.app/0woah.gif)

### Animating it
Add the following code to our JS file:

```javascript
function animateModel() {
  ws.rotate.y += 0.01
  ws.rotate.x += 0.01
  ws.updateRenderGraph()
  requestAnimationFrame(animateModel)
}

animateModel()
```

Explanation:
1. We just created a function that will make the 3D model rotate, you can name this function to whatever you want.
2. `rotate.x` and `rotate.y` set’s the velocity to the rotation of the model:
    - The cube will move up and down depending on the given value (- or +, respectively)
    - The cube will move to the right and to the left depending on the given value (- or +, respectively)

3. `ws.updateRenderGraph()` updates and render your Zdog illustration that was declared in the first variable, make sure to write the correct name in.
4. `requestAnimationFrame(animatemodel)` this is like a loop, basically it makes the model rotates every time by creating frames.
5. `animateModel()` calls the function.

Now you can click on run again!

![Animated model](https://cloud-djkuut7y4.vercel.app/0screen_recording_2020-10-03_at_7.31.47_pm.gif)

Amazing, huh?

![Amazing gif](https://cloud-hrs0t8jeh.vercel.app/0tenor.gif)

Now, go ahead and experiment with the other shapes offered by Zdog (spheres, cylinders, cones, or even custom shapes) and explore the possibilities for creating your own unique 3D models!

### Multiple Shapes
If you want to try and make more complex models you will need to use multiple shapes, [here](https://zzz.dog/#made-with-zdog) are some examples of what you can create:

![examples](https://cloud-2jaw6a14x.vercel.app/0image.png)

Making multiple shapes is very easy, it’s as simple as putting multiple shapes together until you get what you want. The hardest part of this is to put everything where it must be, we can do this using the property: “translate”. 

You can use this property by creating your own complex illustration, which explores hierarchical structures, grouping shapes, and experimenting with positioning and transformations. We'll see how this works when creating a Hack Club logo! Click [here](https://repl.it/@wollygfx/Hack-Club-logo) to see the final code.

First, let's change the class of our canvas in the `index.html` file from `model` to `hackclub`.

```html
...
<canvas class="hackclub"></canvas>
...
```

And add a background color for our project in the `style.css` file. You can choose any color for the background of your 3D model using [a library of hex codes](https://www.color-hex.com/).

```css
.hackclub {
  background: #FDB;
}
```

After that, let's go back to the `script.js` file and change the `element` selected by Zdog from `.template` to `.hackclub` and add the `dragRotate` property with the value set to `true` so we can rotate our creation.

```js
const ws = new Zdog.Illustration({
  element: '.hackclub',
  resize: 'fullscreen',
  dragRotate: true
})
```

Next, let's change the properties of our cube so that it turns into a square:

```javascript
new Zdog.Box({
  addTo: ws,
  width: 100,
  height: 100,
  color: '#ec3750',
  stroke: 20,
  translate: { z: -18 },
})
```

1. As seen before, the `addTo` property puts the made shape inside of the main Zdog Illustration.
2. Used the width and height properties to make a perfect square, i didn't give it a depth because it was not needed.
3. The whole square will have the same color (red), so we can use the color property to give the whole shape a single color instead of assigning a color to each face.
4. As mentioned before, the stroke property helps the shape to look a little rounded.
5. The translate property moves the square -18 within the z-axis. You can interpret this as if you were giving a shape a depth, so the shape is moved backwards.

Now I will create the letter 'H', so I'm gonna need 3 more boxes:

```javascript
new Zdog.Box({
  addTo: ws,
  depth: 20,
  width: 20,
  height: 80,
  color: '#fff',
  translate: { z: 18, x: -20 },
})
```

- This time, the shape is moved forward… This creates an space between the red square and this new shape.
- The shape is moved to the left within the x-axis

![result 1](https://cloud-kg0xtr3hs.vercel.app/0image.png)

```javascript
new Zdog.Box({
  addTo: ws,
  depth: 20,
  width: 20,
  height: 40,
  color: '#fff',
  translate: { z: 18, y: 20, x: 20 },
})
```

- This time, we created a new box but way smaller.
- We moved it to the right within x-axis and a little bit down within the y-axis.

![result 2](https://cloud-1nisp19i8.vercel.app/0image.png)

```javascript
new Zdog.Box({
  addTo: ws,
  depth: 20,
  width: 40,
  height: 20,
  color: '#fff',
  translate: { z: 18, x: 10 },
})
```

In this last one, all we had to do was to move the box to the right within the x-axis, so that it blends with the box in the right.

![result 3](https://cloud-m2gpkvlqa.vercel.app/0image.png)

Now let's update the animation function with some simple properties:

```javascript
function animateModel() {
  ws.rotate.y += 0.01
  ws.updateRenderGraph()
  requestAnimationFrame(animateModel)
}

animateModel()
```

Here's the final result:

![final result](https://cloud-d9lxnrldx.vercel.app/0screen_recording_2020-10-09_at_12.05.02_pm.gif)

### Level up
Congratulations! You just learned the basics of Zdog, feel free to check the resources below to improve your knowledge...

![Congrats gif](https://cloud-d0aqa4icc.vercel.app/0bec38a05d56ac6ae2d9dec2f482ebff9.gif)

Make your own 3D Model and share it in the [Hack Club Slack](https://hackclub.slack.com), I would love to see what you can create using what you've learned in this workshop!

Now that you know the basics, you may be wondering where to go from here. Well, look no further, I've left a list of challenges for you to spice up your project and become a 3D modeling expert!

🌶️ __MILD:__
- Interactive Animation:
	- Research Zdog's event handlers, such as 'onDrag' or 'onClick', to capture user input.
	- Use event listers to detect mouse or touch events and modify properties of your 3D model accordingly.
	- Look through Zdog's GitHub repository and CodePen to see examples of interactive Zdog projects.
- Creating Complex Compositions
	- Plan out your compositions in advance with a pen/paper or digital design tool (I recommend Procreate or Krita).
	- Experiment with positioning, rotation, and scaling properties until you reach your desired outcome.
	- Review Zdog's group property and explore ways to use it for managing multiple shapes together.

🌶️ 🌶️ __MEDIUM:__
- Camera Movement:
	- Look at Zdog examples and tutorials that showcase camera manipulation to learn different approaches and techniques.
- Lighting and Shading: 
	- Research libraries and frameworks with advanced rendering capabilities, such as [Three.js](https://threejs.org/) or [Babylon.js](https://www.babylonjs.com/), which offer support for materials, textures, and opacity.transparency effects in 3D rendering.
	- You can also achieve the effect of different opacities by experimenting with color theory, changing the colors of surfaces and the backdrop, and more!

🌶️ 🌶️ 🌶️ __HOT:__
- Advanced Interactions:
	- Create advanced interactions by using libraries and frameworks in tandem with Zdog.
		- [React.js](https://react.dev/) and [Vue.js](https://vuejs.org/), which are used for creating user interfaces, can be used to create complex and interactive scenes using event handling and component lifecycle management 
		- Interactive SVG libraries like [Snap.svg](http://snapsvg.io/), or Canvas libraries like [Paper.js](http://paperjs.org/about/) can create complex interactions, animations, and event handling capabilities.


### Other examples
Check out these cool 3D models made by other people:

- [Live digital clock made using Zdog](https://codepen.io/jh3y/pen/vqYLKd)
- [Amethyst from Steven Universe made using Zdog](https://codepen.io/Metahari/pen/dEQMBy)
- [Octocat made using Zdog](https://codepen.io/defunty/pen/vwwjPL)

### Resources
- [Zdog website](https://zzz.dog)
- [Made with Zdog](https://codepen.io/collection/DzdGMe/?cursor=ZD0xJm89MSZwPTEmdj0z)
- [Text plugin for Zdog](https://jaames.github.io/zfont/)
- [Plotting data with Zdogs](https://observablehq.com/@zechasault/images-drawn-with-zdogs)

Create Your Own Animated 3D Model


At the end of this jam, we'll create a social media app that handles users and posts.
We'll be using [Firebase](https://firebase.google.com) SDKs to help us with user authentication and data storage.

Here's a demo of something you could build:
![Demo](https://cloud-aspwulevx-hack-club-bot.vercel.app/0document.png)

[Link To Live Demo](https://demo.jaden.mov)

<Dropdown title="Leader notes">

This jam is more suited toward a collaborative environment, so try to divide jammers into teams. One group could focus on designing the app, another could focus on the front end, and another could focus on the back end.

</Dropdown>


#### Pre-requisites

Ideally, you have a basic understanding of HTML, CSS, and JavaScript, but if this is your first jam, feel free to ask for help!

## Brainstorming

<Dropdown title="Brain Fact!">
The human brain weighs 3 pounds
</Dropdown>
The foundation of any social media app is creating and loading some sort of post. Think of any popular social media (Instagram, Reddit, YouTube, or even a recipe app). Share your ideas with the club!

## Setting up

Please fork/clone [this Repl.it boilerplate](https://replit.com/@JadenHou1/JAM) to get started! We'll go over the files in a sec.

```
index.html
login.html
```

These are the two pages we'll be using for our app. `index.html` is the home page where we'll load all the posts and login, and `create.html` is the page where users can create posts.

On each page, we have a basic HTML boilerplate with script and style tags. Conventionally, you'd have these in other files and link them to the HTML file, but for simplicity, we'll just keep them in the same file.

### Creating a Firebase account

Head over to [Firebase Console](https://console.firebase.google.com/u/0/) and log in with Google. Once you're in, create a new project and name it whatever you want.

Then, click and enable `Authentication` and `Firestore Database`.
![Console](https://cloud-5uj5nkwmd-hack-club-bot.vercel.app/0image-1.png)

**Authentication**

1. Click `Get Started`
2. Click `Sign-in method` and enable `Google`
3. Enable and save

If you're using Replit, add your domain by going into Settings > Authorized Domains and add your project's domain. If you don't add the domain (localhost is already added), the authentication pop-up will close instantly.

**Firestore**

<Dropdown title="Shark Fact!">
Sharks...do not have bones
</Dropdown>

1. Click `Start in test mode`
2. Click `Next` and choose `nam5` as the location

### Creating an app in Firebase

![Console](https://cloud-aal2o35z9-hack-club-bot.vercel.app/0image-3.png)

1. Click the `</>` icon
2. Name your app anything
3. Click `Use a <script> tag`
4. Keep this code snippet on hand, we'll need it later

Here is what the code snippet looks like and what each line does:

```html
<script type="module">
    import { initializeApp } from "https://www.gstatic.com/firebasejs/10.0.0/firebase-app.js"; // imports the initializeApp function from the Firebase SDK
    const firebaseConfig = {
        apiKey: "AIzaSyBdD6AmLOxx0b7MPc9FggPMYpttLq-XEE4",
        authDomain: "jammer-7b6da.firebaseapp.com",
        projectId: "jammer-7b6da",
        storageBucket: "jammer-7b6da.appspot.com",
        messagingSenderId: "789182152948",
        appId: "1:789182152948:web:380ac8c7beb26882569ea1",
    }; // specific details unique to your web app. This lets Firebase know that you want to access your services and not someone else's
    const app = initializeApp(firebaseConfig); // load the Firebase app
</script>
```

> Use your own code snippet! This code snippet won't work for you.

## Logging in

![Logs](https://cloud-aal2o35z9-hack-club-bot.vercel.app/1image-4.png)

Head over to `index.html`. Firebase makes it super easy to add user authentication to your app. We'll be using Google Sign-In, but you can use any of the other methods Firebase provides.

First, create a button with `Sign in with Google`. We'll use the id `login` to add an event listener.

```html
<button id="login">Sign in with Google</button>
```

Firebase gives us a really useful `signInWithPopup` and `GoogleAuthProvider` to handle user authentication.

First, add your **Firebase code snippet** from before to the script tag.

Then, import these Firebase functions. This lets us use pre-written functions in our code. Specifically, we want to use `getAuth` to load the authentication, `signInWithPopup` to prompt the user with a popup to log in, and `GoogleAuthProvider` to tell Firebase that we want to use Google.

```js
import {
    getAuth,
    signInWithPopup,
    GoogleAuthProvider,
} from "https://www.gstatic.com/firebasejs/10.0.0/firebase-auth.js";
```

Initialize `getAuth` and the `GoogleAuthProvider`.

```js
const auth = getAuth();
const provider = new GoogleAuthProvider();
```

Now, we can add an event listener to the `login` button. Try making it so that when the user clicks the button, we call `signInWithPopup`.

<Dropdown title="Solution!">

```js
document.getElementById("login").addEventListener("click", () => {
    signInWithPopup(auth, provider).then(() => {
        window.location.replace("/"); // redirect to home page after logged in
    });
});
```

</Dropdown>

<Dropdown title="Your HTML Body should look something like this when finished.">

```html
<button id="login">Sign in with Google</button>
<script type="module">
    import { initializeApp } from "https://www.gstatic.com/firebasejs/10.0.0/firebase-app.js";
    import {
        getAuth,
        signInWithPopup,
        GoogleAuthProvider,
    } from "https://www.gstatic.com/firebasejs/10.0.0/firebase-auth.js";
    const firebaseConfig = {
        apiKey: "AIzaSyBdD6AmLOxx0b7MPc9FggPMYpttLq-XEE4",
        authDomain: "jammer-7b6da.firebaseapp.com",
        projectId: "jammer-7b6da",
        storageBucket: "jammer-7b6da.appspot.com",
        messagingSenderId: "789182152948",
        appId: "1:789182152948:web:380ac8c7beb26882569ea1",
    };
    const app = initializeApp(firebaseConfig);
    const auth = getAuth();
    const provider = new GoogleAuthProvider();

    const login = document.getElementById("login");
    login.addEventListener("click", () => {
        signInWithPopup(auth, provider).then(() =>
            window.location.replace("/")
        );
    });
</script>
```

</Dropdown>

![Login button](https://cloud-aal2o35z9-hack-club-bot.vercel.app/7image-5.png)
Test it out! You should receive a prompt to login. <small>[Need help?](https://firebase.google.com/docs/auth/web/google-signin)</small>

## Creating a post

![Alt text](https://cloud-aal2o35z9-hack-club-bot.vercel.app/3image-7.png)

<Dropdown title="Whale Fact!">
Whales can get SUNBURNS
</Dropdown>

Head over to `create.html`. This is where we'll let users create posts. I'll have to leave these fields up to you, but I'll give you a starting point. Please add fields that are relevant to your idea!

**From now on, your code will depend on the idea you came up with.** For me, I'm going with your average dog personality-sharing app.

First, create a form for users to enter their information.

```html
<form id="form">
    <input id="name" type="text" placeholder="Name" />
    <input id="description" type="text" placeholder="Description" />
    <button type="submit">Submit</button>
</form>
```

> The fields `name` and `description` can be anything you want. Add fields that make sense for your app! For example, a recipe app may have an estimated time to make, and a club directory app may have meeting times.

This is just a basic form with 2 inputs and a submit button. Adding IDs to each input allows us to access the values on submit. Adding an ID to the form allows us to add an event listener to it.

To add these fields to the database, we have to import some new packages! First, add the **Firebase code snippet** from before to the `<script>`. Then, import both the **authentication functions from before** and the `getFirestore`, `setDoc`, and `doc` functions from **Firestore** as follows.

```js
import {
    getAuth,
    signInWithPopup,
    GoogleAuthProvider,
} from "https://www.gstatic.com/firebasejs/10.0.0/firebase-auth.js";
import {
    getFirestore,
    addDoc,
    doc,
} from "https://www.gstatic.com/firebasejs/10.0.0/firebase-firestore.js";
```

Importing `getFirestore`, `addDoc`, and `doc` allows us to load Firestore, add documents to the database, and reference a document in the database, respectively.

Load each package.

```js
const auth = getAuth();
const db = getFirestore();
```

Then, access the form element, and add an event listener to listen for form submissions.

```js
form.addEventListener("submit", (e) => {
    e.preventDefault();
});
```

By default, forms will refresh the page on submit. We don't want this because we won't be able to execute code if the page is refreshing, so we'll add `e.preventDefault()` to prevent the page from refreshing.

We don't want just anyone to add posts, just users! So, we'll add a check to see if the user is logged in. If they are, we'll add the post to the database. If not, we'll alert them to log in.

Add the following after the `e.preventDefault()`.

If I can get the current user by using `auth.currentUser`, how would I check if there is no current user?

<Dropdown title="Solution!">

```js
const currentUser = auth.currentUser;
if (!currentUser) {
    alert("Please login first");
    return;
}
```

</Dropdown>

`auth.currentUser` lets us access the current user. If there is no current user, the variable will be `null`, so we can alert the user and not add anything. `return` will stop the function from executing any more code.

Then, create a collection in Firestore. A collection holds all your documents. It's like a bucket for all your data.
![Alt text](https://cloud-aal2o35z9-hack-club-bot.vercel.app/4image-8.png)
![Alt text](https://cloud-aal2o35z9-hack-club-bot.vercel.app/5image-9.png)

> Choose a collection name that makes sense for your app! It doesn't have to be posts if that doesn't make sense. Maybe something like `recipes` or `clubs` would make more sense for your idea

When you're prompted to create the first document, add sample data for the fields you've already created above. You can just click auto-ID for the document ID.
_For example, in my case I'll add `name` and `description`._
![Alt text](https://cloud-aal2o35z9-hack-club-bot.vercel.app/6image-10.png)

Now, we can access the values of each input and add them to the database. We'll use `addDoc` to add a document to the database. `addDoc` takes in 2 parameters: the reference to the collection and the data to add. We'll use `collection` to reference the collection we want to add to, `name.value` to get the value of the first input, and `description.value` to get the value of the second input. We can also use `currentUser.displayName` to grab the name of the author to display.

```js
const form = document.getElementById("form");
const name = document.getElementById("name");
const description = document.getElementById("description");
addDoc(collection(db, "posts"), {
    name: name.value,
    description: description.value,
    author: currentUser.displayName,
});
```

> Your `name` and `description` variables will vary based on the fields you set. Be sure to change them to match this format: `const <field> = document.getElementById("<field>")`. Also, the key/values in the data we're adding will vary.

Finally, we'll let the user know that they've successfully submitted a post.

```js
alert("Successfully submitted post!");
```

<Dropdown title="Your HTML Body should look something like this when finished.">

```html
<form id="form">
    <input id="name" type="text" placeholder="Name" />
    <input id="description" type="text" placeholder="Description" />
    <button type="submit">Submit</button>
</form>
<script type="module">
    import { initializeApp } from "https://www.gstatic.com/firebasejs/10.0.0/firebase-app.js";
    import {
        getAuth,
        signInWithPopup,
        GoogleAuthProvider,
    } from "https://www.gstatic.com/firebasejs/10.0.0/firebase-auth.js";
    import {
        getFirestore,
        addDoc,
        collection,
    } from "https://www.gstatic.com/firebasejs/10.0.0/firebase-firestore.js";
    const firebaseConfig = {
        apiKey: "AIzaSyBdD6AmLOxx0b7MPc9FggPMYpttLq-XEE4",
        authDomain: "jammer-7b6da.firebaseapp.com",
        projectId: "jammer-7b6da",
        storageBucket: "jammer-7b6da.appspot.com",
        messagingSenderId: "789182152948",
        appId: "1:789182152948:web:380ac8c7beb26882569ea1",
    };
    const app = initializeApp(firebaseConfig);
    const auth = getAuth();
    const db = getFirestore();
    const form = document.getElementById("form");
    form.addEventListener("submit", (e) => {
        e.preventDefault();
        const currentUser = auth.currentUser;
        if (!currentUser) {
            alert("Please login first");
            return;
        }
        const name = document.getElementById("name").value;
        const description = document.getElementById("description").value;
        addDoc(collection(db, "posts"), {
            name: name,
            description: description,
            author: currentUser.displayName,
        });
        alert("Successfully submitted post!");
    });
</script>
```

</Dropdown>

## Loading posts

This is where it gets good. We'll be loading posts from the database and displaying them on the home page. Head over to `index.html`.

> I'll leave this implementation up to you, but I'll give you some steps to get started.

After the code from the login, import the Firestore from before into the file.

```js
// snippet

import {
    getFirestore,
    getDocs,
    collection,
} from "https://www.gstatic.com/firebasejs/10.0.0/firebase-firestore.js";
const db = getFirestore();
```

To create an element for each post, we'll need to get each post and run a function for each. We'll need `getDocs`. `getDocs` returns a [Promise](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Promises#async_and_await), and we can use `await` to turn that into a value, but we won't get into that in this jam (think of it as a black box).

Here's an example of how to use `getDocs` to get all the posts.

```js
const posts = await getDocs(collection(db, "posts"));
```

Now, we can use [`.forEach`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) to [create elements](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement).

<Dropdown title="Solution!">

```js
const db = getFirestore();
const div = document.getElementById("div");
const posts = await getDocs(collection(db, "posts"));
posts.forEach((doc) => {
    const element = document.createElement("div");
    const name = document.createElement("h1");
    name.innerText =
        doc.data().name +
        " • " +
        doc.data().author;
    element.appendChild(name);
    const description = document.createElement("p");
    idea.innerText = doc.data().description;
    element.appendChild(idea);
    div.appendChild(element);
});
```

> Your code will look different depending on your fields

</Dropdown>

That's it! Now you have a working social media app. It's your job to add CSS, more fields, and more features to make it your own.

## Not-so-full list of customizations
 - Change the styling
 - Change how posts are loaded
 - Change fields
 - Add cosmetic elements


At the end of this jam, you'll create your very own social media app that handles users and posts.


Building Your Own Social Media w/ 🔥 Firebase 🏰


Converting words to colors is a difficult concept to wrap your head around when you first think about it, but that’s exactly what you’re going to do in this workshop. In just 20 lines of code, you’re going to build a website that allows you to type all over the screen and watch the color of your screen change based on the number of verbs, nouns, adjectives, and adverbs in the text.

[**Link to demo**](https://colorful-grammar.techbug2012.repl.co/)
[**Link to demo code**](https://repl.it/@TechBug2012/colorful-grammar)

## Getting started

Create a new Repl.it project at [replit.com/languages/html](https://replit.com/languages/html).

To make things a little easier for us, we’re going to be using [jQuery](https://jquery.com/), a popular JavaScript library that simplifies writing certain common JavaScript tasks. You’ll get to see how jQuery can be really useful throughout this workshop.

We’re also going to use [WordPOS](https://github.com/moos/wordpos), a cool dictionary library that identifies the grammar type of a given word (e.g. noun, verb, etc).

Let’s start by importing these two libraries. Just before the end of the `<head>` tag of your `index.html` file, add these two lines:

```html
<script src="https://code.jquery.com/jquery-3.4.1.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/wordpos-web@1.0.2/dist/wordpos.min.js"></script>
```
## Typing on the screen

Great! Now that we’ve imported the libraries we need to make our website, it’s time to write some code.

In order to use our entire screen as our canvas for writing, we need to create a `<textarea>` in our HTML file and use CSS to make it fill the entire screen.

In the `<body>` of your `index.html` file, under the line where `script.js` is imported, add this line:

```html
<textarea id="sentence" autofocus></textarea>
```

This creates a [textarea](https://www.w3schools.com/tags/tag_textarea.asp) element with the id “sentence”, and automatically focuses on it so that you don’t have to click on it to start typing. If you run your repl, you’ll see this textarea in the top left corner.

In order to be able to use this textarea as our writing canvas, we’ll need to do some CSS work. Namely:

1. Remove the white background
2. Remove the blue outline around the edges
3. Remove the black border around the edges
4. Make it fill the entire screen without overflowing

Start by adding

```css
textarea {
}
```

to your `style.css` file.

To remove the white background, we use `background: none;`. To remove the blue outline, we use `outline: 0;`. To remove the black border, we use `border: 0;`. Add these three [declarations](https://developer.mozilla.org/en-US/docs/Web/CSS/Syntax) inside the `textarea` [block](https://developer.mozilla.org/en-US/docs/Web/CSS/Syntax) of your `style.css` file. When you’re done, the file should look like this:

```css
textarea {
  background: none;
  outline: 0;
  border: 0;
}
```

When you run your repl, you should see that the textarea appears to have disappeared. But if you click at the top left corner of the preview, you’ll notice that you can still type. The textarea is still there—you’ve just made it invisible.

We still need to make the textarea fill the whole screen. Add `width: 100%;` and `height: 100%;` to the `textarea` block in your `style.css` file. While you’re at it, go ahead and also add `font-size: 48px`, which makes the font size bigger.

```css
textarea {
  background: none;
  outline: 0;
  border: 0;
  width: 100%;
  height: 100%;
  font-size: 48px;
}
```

Your textarea still doesn’t quite fill the whole screen, though—these two properties only made it fill 100% of its parent element. In our case, this is the `<body>`, which doesn’t fill the whole screen. We ran into the same problem in the [Splatter Paint Workshop](https://github.com/hackclub/hackclub/blob/main/workshops/colorful_grammar)—check it out for a clearer explanation of this concept.

To make the `<body>` fill the whole screen, simply add

```css
html,
body {
  height: 100%;
}
```

to your `style.css` file.

When you run your repl, you’ll notice that the textarea fills the whole screen! But if you type too much, it’ll shift a little bit to the right, obscuring some of the text. We can fix this by adding `padding: 0;` to the `textarea` block.

Now the textarea fills the whole screen without overflowing!

Just to recap—this is what your entire `style.css` file should now look like:

```css
html,
body {
  height: 100%;
}

textarea {
  background: none;
  outline: 0;
  border: 0;
  width: 100%;
  height: 100%;
  font-size: 48px;
  padding: 0;
}
```

## Coloring our canvas

Now that we can write anywhere on our screen, it’s time to make use of the libraries we imported earlier.

Navigate to your `script.js` file and add the following:

```js
const wordpos = new WordPOS({
  dictPath: 'https://cdn.jsdelivr.net/npm/wordpos-web@1.0.2/dict'
})
```

This initializes a new instance of the WordPOS library with a dictionary to identify words with.

Under this, add

```js
$(document).ready(function () {})
```

This is how jQuery is initialized. Usually when you see a dollar sign in JavaScript, it’s a shorthand for jQuery.

Now, let’s write a function that updates the background of our page inside the jQuery function.

```js
$(document).ready(function () {
  function updateBackground() {}
})
```

Inside the `updateBackground` function, add the line:

```js
let sentence = $('#sentence').val()
```

This uses jQuery to get the value of our textarea, which if you recall, we gave the id “sentence”. You could replace `$(“#sentence”)` with `document.getElementById(“sentence”)`, but the jQuery syntax makes it a little bit easier.

To get the number of each type of word used in the sentence, we need yet another function. Add the following inside the `updateBackground` function:

```js
wordpos.getPOS(sentence).then(function (types) {})
```

As of now, this is what your `script.js` file should look like:

```js
const wordpos = new WordPOS({
  dictPath: 'https://cdn.jsdelivr.net/npm/wordpos-web@1.0.2/dict'
})

$(document).ready(function () {
  function updateBackground() {
    wordpos.getPOS(sentence).then(function (types) {})
  }
})
```

## Converting text to a color

The beauty of this workshop is that there are endless ways you can go about creating a color from all of this data, and each will produce a different result. I’m going to show what I personally came up with, but as you read the next steps, be actively thinking of ways you can change it to do something different.

We’re going to be creating our color with the [HSL (Hue, Saturation, Luminosity) color system](http://thenewcode.com/61/An-Easy-Guide-To-HSL-Color). If you’re not familiar with it, all you need to understand for this demo is that the HSL system uses a color wheel, and you identify a color according to its position on the color wheel in degrees. Also important to note is that colors start a new cycle once you pass 360°. Just like a 60° angle looks the same as a 420 (360 + 60)° angle, 60° on the HSL color system is the same color as 420°: yellow.

[![Color wheel divided into 6 equal parts](https://camo.githubusercontent.com/2550f89160b7c53a6f846c1206c6ba20763f93f2546e981c250c191a48c6935d/68747470733a2f2f636c6f75642d707670766b706575632d6861636b2d636c75622d626f742e76657263656c2e6170702f3168736c2d636f6c6f722d776865656c2e706e67)](https://camo.githubusercontent.com/2550f89160b7c53a6f846c1206c6ba20763f93f2546e981c250c191a48c6935d/68747470733a2f2f636c6f75642d707670766b706575632d6861636b2d636c75622d626f742e76657263656c2e6170702f3168736c2d636f6c6f722d776865656c2e706e67)

Because we can simply identify a color with a number, one way we can process our data is by adding up the frequency of each type of word. Using the WordPOS library, getting the total number of word type is as simple as `types.[type].length`; for example, `types.verbs.length`.

Create a variable that adds up the frequency of every type of word.

```js
var color =
  types.verbs.length +
  types.adverbs.length +
  types.nouns.length +
  types.adjectives.length +
  types.rest.length
```

Now that we have a number that we can create an HSL color with, let’s create it and change the background color. This is where jQuery becomes really useful: we’re going to change the CSS on our page right from our JavaScript file!

```js
$('body').css('background-color', `hsl(${color}, 100%, 50%)`)
```

(Note: in JavaScript, you can use back-ticks instead of quotation marks and concatenate strings using the `${variable}` syntax. The dollar sign next to `hsl` is unrelated to jQuery. Learn more about this syntax [here](https://developers.google.com/web/updates/2015/01/ES6-Template-Strings).)

Here’s what your entire `script.js` file should look like after this:

```js
const wordpos = new WordPOS({
  dictPath: 'https://cdn.jsdelivr.net/npm/wordpos-web@1.0.2/dict'
})

$(document).ready(function () {
  function updateBackground() {
    let sentence = $('#sentence').val()

    wordpos.getPOS(sentence).then(function (types) {
      var color =
        types.verbs.length +
        types.adverbs.length +
        types.nouns.length +
        types.adjectives.length +
        types.rest.length

      $('body').css('background-color', `hsl(${color}, 100%, 50%)`)
    })
  }
})
```

We’re almost done! The final step is to run the `updateBackground()` function once when the page loads and then each time a new letter is typed.

Right before the last closing curly brace, add these two lines:

```js
updateBackground()
$('#sentence').on('keydown', updateBackground)
```

Now, your `script.js` file should look like this:

```js
const wordpos = new WordPOS({
  dictPath: 'https://cdn.jsdelivr.net/npm/wordpos-web@1.0.2/dict'
})

$(document).ready(function () {
  function updateBackground() {
    let sentence = $('#sentence').val()

    wordpos.getPOS(sentence).then(function (types) {
      var color =
        types.verbs.length +
        types.adverbs.length +
        types.nouns.length +
        types.adjectives.length +
        types.rest.length

      $('body').css('background-color', `hsl(${color}, 100%, 50%)`)
    })
  }
  updateBackground()
  $('#sentence').on('keydown', updateBackground)
})
```

When you run your repl, you should be greeted by a blank red screen. Click on the preview and start typing a bunch of words. You should see the background color change as you type each word!

## Hacking

Your journey is far from over. There are endless ways you can make this your own. Here are a few suggestions:

1. If you feel like the background color is changing too slowly, try multiplying your `color` variable by a number so that it goes around the HSL color wheel more quickly.
2. Why make your background only one color? How about using the CSS [linear-gradient](https://developer.mozilla.org/en-US/docs/Web/CSS/linear-gradient) function? [Check out what I did](https://repl.it/@TechBug2012/colorful-grammar) for an example of what this looks like. There are many, many different ways you can make a gradient!
3. I kept the saturation and luminosity of my color at 100% and 50%, but that doesn’t mean you have to! Try changing those numbers around and see how many new colors you can create.
4. Change the font and size of the text in the textarea

...and much, much more!

Your new task is to hack away at this project until it looks noticeably different from this demo and is totally your own. Go crazy, and good luck!


Let your words color the screen as you type!


Color the Screen with Your Words


## Intro

> Appreciate the ends without understanding the means.

In this jam, you'll design a small trinket. Don't know what it is yet, but discovering it will be part of the activity.

Instead of "Learn to make a hacker card" or "Learn to make a digital level", we're going to make something perfectly useless!

## Random part picker!

You're going to go to this [magical part picker site](https://component-hat-site.hackclub.dev/), 

1. **First roll the dice** get a random input, output, and power source.
2. **Come up with an idea** that combines the components into a fun useless gadget.
3. **Draw some art** to put on your board

Here's an example of what you might end up with (EXCEPT YOU'RE NOT GOING TO HAVE THIS SAME IDEA & THE SAME COMPONENTS):

Combine a **Light Sensor**, **Rumble Motor**, and **Battery** to make a rattle snake that rumbles whenever you put it in the light.

![rattleSnake](https://cloud-62nxyioni-hack-club-bot.vercel.app/0drawing__7_.png)

No one has ever sat down to learn web dev & made the next facebook. Similarly, if you sit down thinking "I'm going to make something as helpful as an iPhone", you're destined for failure...

But sit down to make some trash, and you'll end up with this treasure:

![board color](https://cloud-plhykfmfn-hack-club-bot.vercel.app/0screenshot_2024-03-13_at_3.23.48_pm.png)

## Get In Your Workspace

Now it's the time to open up good ol' [easyeda](https://easyeda.com/)

Step 1: create an account or login with google (tapping Register in the top right corner)
![loginWithGoogle](https://cloud-8c6bzxhxx-hack-club-bot.vercel.app/0registereda.gif)

Step 2: Tap on Easy EDA Designer Open the "STD" (student) edition of EasyEDA
![STDEdition](https://cloud-8lt1ycvzx-hack-club-bot.vercel.app/0easyeda_designer.gif)

Step 3: Start A New Project
![NewProject](https://cloud-3oval3xig-hack-club-bot.vercel.app/0newproject.gif)

## Add In Your Components

Add your components to the schematic zone (the non-creative zone).

You can do this by pulling up [this component library](https://hackclub.github.io/OnBoard/site/index.html) we made and then selecting the components you drew out of the hat. 

Once you select a component
1. Get the part number from the markdown 
2. Open up EasyEDA Library (on the side bar)
3. Search for your component (tap search icon)
4. Select your component and place it anywhere on your schematic

![Light Sensor](https://cloud-lvwqcxzv9-hack-club-bot.vercel.app/0getcomponentid.gif)

Repeat this step for all 3 of your components

![your components](https://cloud-ecs518tqh-hack-club-bot.vercel.app/0screenshot_2024-03-13_at_2.48.02_pm.png)

## Wire the components up

Look at the documentation for each component in the [component library](https://hackclub.github.io/OnBoard/site/index.html), and see how it is wired up. Follow the documentation examples to wire up your input, output, and power source.

Use R to rotate your elements and drag them around. Remember this is the NO CREATIVITY ZONE because your design will be totally moved around when you convert it to a PCB. 

![wired up](https://cloud-gsil8fuxg-hack-club-bot.vercel.app/0screenshot_2024-03-13_at_2.48.14_pm.png)


## Convert to PCB

Save your design (control S or CMD S)

Tap Convert To PCB under Design -> "Convert To PCB"
![conver to schematic](https://cloud-g1kkox8xj-hack-club-bot.vercel.app/0converttoschematic.gif)

Rotate your components to minimize the rat lines (these subtle blue lines) crossing over each other. It's okay if it happens sometimes, but minimize the amount of times. 

![noRatsCrossing](https://cloud-3ts8mn0bw-hack-club-bot.vercel.app/0screenshot_2024-03-13_at_2.57.23_pm.png)

Then use the Track Tool (W) to begin connecting the rat lines

![connectRats](https://cloud-q6a3ktc2y-hack-club-bot.vercel.app/0connectrats.gif)

## Getting Artistic 

Now, throw your art into the schematic! This will be on a silk layer, so it will not impact your wiring.

![Make First Pcb](https://cloud-l9r67m3n3-hack-club-bot.vercel.app/0add_in_the_art.gif)

You now need to make you art into a silk layer

![makeYellow](https://cloud-pihem7ix9-hack-club-bot.vercel.app/0silklayer.gif)

Next, move your components to make them fit your design.

![movedAround](https://cloud-d4z0ripa1-hack-club-bot.vercel.app/0screenshot_2024-03-13_at_3.18.18_pm.png)

It's time to cut out your board! 

![cut out](https://cloud-7kaunz432-hack-club-bot.vercel.app/0outline.gif)

Now you may have some loose wires or some rat lines that are not connected yet. Connect all of your loose wires to components and fix any of the yellow xs (that means your lines are crossing in a way that will cause a problem)

![Here is a snake](https://cloud-8uy971i40-hack-club-bot.vercel.app/0screenshot_2024-03-13_at_3.45.18_pm.png)

Boom... now you have a PCB!

![board color](https://cloud-plhykfmfn-hack-club-bot.vercel.app/0screenshot_2024-03-13_at_3.23.48_pm.png)

You should now go & order this board! 

## Ready to buy?

You can get your board made for free with Hack Club's OnBoard project.

Check out the steps for getting your board for free [here](https://onboard.hackclub.com/).

Let's build a hacky electronics gizmo -- but with a twist -- you can only use three components that you draw out of a cap! You'll learn the basics of designing a PCB, and you can get the cards made for free, with Hack Club's OnBoard.

Make Your Own Electronic Trash Out Of A Magical Hat

> For the Code Snippets PDF, [click here.](https://cloud-gdufd98x3-hack-club-bot.vercel.app/0code_snippets.pdf)

# Introduction
Winter is objectively the best season of the year. Hot cocoa, pine trees, family tradition, sledding, and, most importantly, snow, are all favourites from this cozy season. However, winter doesn't last forever, and snow melts, much to the dismay of every five-year-old with a snowman. But, we humans have made a solution... snowglobes!

![https://cloud-fcssxnb6l-hack-club-bot.vercel.app/](https://cloud-fcssxnb6l-hack-club-bot.vercel.app/6snow_doge.png)]

So much snow in a small sphere?!? What much more could a person want?

![https://cloud-fcssxnb6l-hack-club-bot.vercel.app/](https://cloud-fcssxnb6l-hack-club-bot.vercel.app/7power_graph.png)
> It's scientifically proven!

So, how would you like to create your own, virtual, shareable snowglobe? (I guess you don't have a choice at this point because, spoiler alert, you are doing that right about now...)

## What We're Making

![https://cloud-782rtf1du-hack-club-bot.vercel.app/0ezgif.com-resize.gif](https://cloud-782rtf1du-hack-club-bot.vercel.app/0ezgif.com-resize.gif)

In this jam, we'll be making a custom, digital snowglobe (as implied by the title!) You'll be able to choose the background, particles, or even the music. [Here's a live demo of what we're building.](https://snowglobe.judahbrown.dev/)

# The Basics

> If you'd like to skip ahead to the fun part, or if you're short on time, you can use [this template on replit to get started!](https://replit.com/@VelocityDev/snowglobe-template) Just hit the "use template" button at the top of the page and skip ahead to the "Make it look Fabulous" section (note: the particles.json file is already in place.) This template comes with the 'Make it Installable' customization already added as well.

## Setting the Page Up
Every good project starts with a plan! Here, we'll link to some essential libraries and lay out the page. We'll be using basic HTML, intermediate CSS, and more advanced JavaScript, but it's really easy to figure out!

> [For a video on some HTML basics, click here!](https://www.youtube.com/watch?v=salY_Sm6mv4)

### 🦴 Add the Skeleton
While some skeletons are spooky-scary, these skeletons are actually really useful! A page skeleton is just the basic HTML that every website should have, such as a `<!DOCTYPE>`, `<html>` tags, and a `<head>`/`<body>`.

> For more information on the basics of an HTML page, watch (LINK TO BE ADDED)

### ⛓ Linking Libraries
Now, to link the `tsParticles` library.
tsParticles is available as a single file from JSDeliver. Link to it using a `<script>`  tag at `https://cdn.jsdelivr.net/npm/tsparticles@2.11.0/tsparticles.bundle.min.js`.

### Lay it all Out
To lay out our page, we'll be using `div`'s (inside of the `<body>` tag) which allow us to split the page into separate areas. They can be nested inside of each other and stylized with CSS. Let's make a `snowglobe` div with sections `particles` and `ground`...

```html
...
<div id="snowglobe">
	<div id="particles">
	</div>
	<div id="ground">
	</div>
</div>
...
```

We'll leave these `div`'s empty, but they'll serve an important role in laying out our page.

### 🖌 Make it look ✨ fabulous ✨
CSS is a language that allows us to style HTML pages! With it, we can resize elements, change fonts, mess with colors, and even animate things!

To start, let's reset all of the spacing!

```css
* {
	padding: 0;
	margin: 0;
}
```

Next, we'll set up flex display on body. Make sure to set its `flex-direction` to `column`. Additionally, we'll make the body fill the whole viewport, set its background color (feel free to change this! this is the page background, not the snowglobe background), and make it center all the items with `justify-content` and `align-items`.

```css
body {
	/* Set up flex display */
	display: flex;
	flex-direction: column;
	
	/* Fill the whole viewport */
	width: 100vw;
	height: 100vh;
	overflow: hidden; /* Hide all overflow */
	
	/* Center the items */
	justify-content: center;
	align-items: center;
}
```

> [For more information on Flex, read this article!](https://www.w3schools.com/css/css3_flexbox.asp)

Now, we'll set up the globe itself. First, we'll want to make the globe take up as much of the screen as possible. To do this, we'll use CSS's `vmin` unit to use the smallest screen dimension as a reference. To add some margin, we'll only want to take up around 85% of this space (so... `85vmin`). Next, we'll set the background to a nice, balmy blue (`#45b3e0`, to be exact.) After that, we'll round off the snowglobe by setting `border-radius` to 100%. We'll hide the `overflow` in order to keep things within limits. Then, we'll set the `margin` to `auto` in order to make the globe flow nicely within its new home. Finally, we'll add a nice glow effect!

```css
#snowglobe {
	/* Set the sizing*/
	width: 85vmin;
	height: 85vmin;
	
	/* Nice, but temporary, background */
	background: #45b3e0;
	
	/* Make the globe round */
	border-radius: 100%;
	overflow: hidden;
	
	/* Add some nice spacing */
	margin: auto;
	
	/* And finally, add a nice glow*/
	box-shadow: 0px 0px 20px 35px #FFFFFF05;
}
```

Adding the ground and particle settings are easy at this point... we'll have the ground take up just 25% of the snowglobe and leave the rest to the sky.

```css
#particles {
  height: 75%;
  width: 100%;
}

#ground {
  height: 25%;
  width: 100%;
  background: #bebebe; /* You can change this now or later if you want */
}
```

#### Bonus: A shake animation!
If you want, we can add a fun little shake animation for whenever the snowglobe is activated! First, we'll add some springy keyframes. Then, we'll add a class called "shake" that we'll add to the snowglobe once it's activated.

```css
@keyframes shake {
	0%,
	100% {
    transform: rotate(0deg);
	}
	
	25% {
    transform: rotate(15deg);
	}
	
	50% {
    transform: rotate(-15deg);
	}
	
	75% {
    transform: rotate(10deg);
	}
}

.shake {
  animation: shake 1s;
}
```

> [Read more about CSS Animations here!](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations)

### Script it up!
Now, after everything else is done, let's get the dirty work done!

First, we'll add another script tag after the `snowglobe` div. Inside, we'll start writing some javascript. Let's declare some variables real quick...

```js
	// Select the globe
	let globe = document.getElementById("snowglobe");
	
	// Declare particles
	let particles;
```

Next, we'll add a function that will help us later on with activating the snowglobe when a device is shaken. This will accept an input event from the motion sensor on a device and calculate the magnitude with which the device was shaken. First, we'll grab the acceleration from the sensor. Then, we'll use a mathematical function that calculates the magnitude using those values. The function will finally return the result of that calculation.

```js
	// Declare function for calculating Gyro activity
	function calculateAcceleration(event) {
		const {x, y, z} = event.accelerationIncludingGravity;
		const accelerationMagnitude = Math.sqrt(x * x + y * y + z * z);
		return accelerationMagnitude;
	}
```

Finally, we'll add the function to handle shaking activation!

```js
	function shakeItUp() {
		particles.play();
		
		// Only include this code if you're making the shake animation
		globe.classList.add("shake")
		setTimeout(() => {globe.classList.remove("shake")}, 1100)
	}
```

### ↕ Choices, choices
Now, time to tie it all together! tsParticles can load particle configuration in a number of ways, but one of the easiest is to load it from a `.json` file. Go ahead and download [this default snow configuration](https://cloud-66d7j3kh5-hack-club-bot.vercel.app/0particles.json) and place it in your website root as `particles.json`. You can customize these values later.

Under the `calculateAcceleration()` function, add the command `tsParticles.load()`, which allows us to load the configuration. This command takes two inputs, element ID and configuration. Our element ID is the ID of the element where we want the particles to appear, and our configuration is the path to our config file, `particles.json`.

```js
tsParticles.loadJSON('particles', 'particles.json')
```

Next, we'll add a callback function. Inside we'll select the particles container and immediately pause the particles until they're shaken.

```js
    tsParticles.loadJSON('particles', 'particles.json')
      .then(function () {
        // Select the particle container and pause the particles
        particles = tsParticles.domItem(0);
        particles.pause()
```

Then, we'll add an event listener that calls the `shakeItUp()` function whenever the snowglobe is clicked/touched.

```js
        // Add globe event listener
        globe.addEventListener('click', () => {
          shakeItUp()
        });
```

 Then, we'll add an event listener that calls the `shakeItUp()` function whenever the snowglobe is clicked/touched. Finally, we'll add an event listener to the `window` element (provided by default) that detects gyroscope shifts and calculates its magnitude. Finally, it will compare this magnitude to a threshold (in testing, values between 17-23 seemed to work best) which can be adjusted if needed.  If this comparison passes, then it will call `shakeItUp()`. This is a lot at once, so take a look at the code below.

```js
    tsParticles.loadJSON('particles', 'particles.json')
      .then(function () {
        // Select the particle container and pause the particles
        particles = tsParticles.domItem(0);
        particles.pause()

        // Add globe event listener
        globe.addEventListener('click', () => {
          shakeItUp()
        });

        // Add gyro event listener
        window.addEventListener("devicemotion", (event) => {
          // Calculate the magnitude every time
          const acceleration = calculateAcceleration(event);

          // Compare the magnitude to threshold.
          if (acceleration > 23) {
            shakeItUp()
          }
        });
      });
```

And, that's all!

> [For more information on what event listeners are and how they work, check out this article!](https://www.computerhope.com/jargon/e/event-listener.html/)

# Customization
At this point, you have a nice, amazing snowglobe. Congratulations 🎉
However, it's looking like all of these snowglobes are the same...

![https://cloud-fcssxnb6l-hack-club-bot.vercel.app/](https://cloud-fcssxnb6l-hack-club-bot.vercel.app/8identical_snowglobes.png)

Let's fix that by spicing them up a bit!

## Setting the Setting (Adding a background)

### Adding an Image
Adding an image is super simple! If you don't have an image you'd like to use already, you can find one on a free service like [Unsplash!](https://unsplash.com/) 

![https://cloud-fcssxnb6l-hack-club-bot.vercel.app/](https://cloud-fcssxnb6l-hack-club-bot.vercel.app/3mountains.png)
> For example, this one.

Download the image and add it to the website folder (Err- upload it to your repl!) For simplicity, let's rename the file to `background.jpg` (or `.png`, etc.) Now, go into the CSS for the `#snowglobe` element. Let's change up that background...

```css
#snowglobe {
	background: url('/background.jpg') center/cover;
}
```

Now, if you want to change up the position of the image within the globe, just change `center` in `center/cover`  to another location such as `right`, `top`, or `bottom`.

![https://cloud-fcssxnb6l-hack-club-bot.vercel.app/](https://cloud-fcssxnb6l-hack-club-bot.vercel.app/4picture_globe.png)
> Hurrah, cool mountains!

### Adding a Gradient
To keep it simple, you can use a tool like [cssgradient.io](https://cssgradient.io/) to generate a cool gradient background. Once you're done, all you need to do is copy the part that starts with `linear-gradient`.

![https://cloud-fcssxnb6l-hack-club-bot.vercel.app/](https://cloud-fcssxnb6l-hack-club-bot.vercel.app/2gradient_highlighted.png)
> Just the highlighted part!

Next, go into the CSS for the `#snowglobe` element. Let's change up that background...

```css
#snowglobe {
	/* You'll replace the gradient here with your own */
	background: linear-gradient(4deg, rgba(134, 100, 0, 1) 0%, rgba(121, 9, 9, 1) 32%, rgba(4, 0, 70, 1) 100%);
}
```

![https://cloud-fcssxnb6l-hack-club-bot.vercel.app/](https://cloud-fcssxnb6l-hack-club-bot.vercel.app/5gradient_globe.png)
> A cool sunset made with the gradient `linear-gradient(4deg, rgba(134, 100, 0, 1) 0%, rgba(121, 9, 9, 1) 32%, rgba(4, 0, 70, 1) 100%)`

If you want an extra cool challenge, try animating it! See [the section on animation above](#### Bonus: A shake animation!) and try to figure it out for yourself!

> [If you'd like to learn more about CSS Gradients, you can read this article from MDN!](https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/linear-gradient)

## It's raining, It's pouring! (Change what's falling)
To change what's falling, we'll need to go into the `particles.json` file. Here, we can change animation, color, or even shape!

### Change the Color
Changing the color is super easy! Just locate the `colors` object within `particles`. If you're using the default configuration, it should be near line 30. Change the `value` within this to whatever color you want and then you'll be good to go!

### Change the Shape to a new Shape
By default, tsParticles allows you to use one of three different shapes: `square`, `circle`, and `triangle`. To change this, simply locate the `particles.shape` object within `particles.json`. If you're using the default config, this is located near line 129. Within this object, change the `type` to the shape you want. Ta-da! Now you have a new shape!

### Make More Stuff Fall
tsParticles allows you to adjust a `number` value to make more or less particles fall. It uses a density calculator to scale this value up or down, too. This value in the default config is located near line 106, under the `particles.number` object. Change the `value` to whichever value you'd like.


## Twinkle, Twinkle (Add some music)
First find some music! Legally, you should use some audio to which you have rights. [Check the internet archive for something to use!](https://archive.org/) 

Anyway, you'll want to download that audio and add it to the website directory (or upload it to your repl.) For simplicity, rename the file to `audio`. Under the `snowglobe` div, go ahead and add a new `audio` element with a single `source` child.

```html
<audio id="music">
	
	<source src="audio.ogg" type="audio/ogg"></source>
</audio>
```

Now, select the audio element. Then, add the line `music.play();` into the `shakeItUp()` function. 

```js
let music = document.getElementById('music')
...
function shakeItUp() {
	...
	music.play()
}
```

Congratulations, now you have music!

## It's an App! (Making it a PWA)
At this point, you have a cool snowglobe that's custom to you. Now, you can make it installable. Thankfully, you don't need to do much to create it as an installable app. You won't even need to have an App Store Developer account.

In order to do this, we'll use a web technology called a Progressive Web App (Or, PWA for short.) PWA uses a combination of smaller web technologies, like web manifests that declare your site and its content and service workers that allow your site to cache content and run in the background. All in all, it creates a neat little package for a web app.

To start, download [these assets](https://cloud-osijhtm8u-hack-club-bot.vercel.app/0pwa.zip) and unzip them into the root of your project. If you want, you can generate these assets with a custom icon and color scheme using a tool like [Real Favicon Generator](https://realfavicongenerator.net/), my personal favourite. Now, add the following HTML to the end of your head:

```html
  
  <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
  <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
  <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
  <link rel="manifest" href="/manifest.json">
  <link rel="mask-icon" href="/safari-pinned-tab.svg" color="#3063ac">
  <meta name="apple-mobile-web-app-title" content="Snowglobe">
  <meta name="application-name" content="Snowglobe">
  <meta name="msapplication-TileColor" content="#2b5797">
  <meta name="theme-color" content="#2e2e2e">
```

> Note: If you're using a custom pack, follow the instructions that they give instead.

Now, if all has gone well, you should be able to install the website as a PWA! Congratulations! If you need help with this, [check out this article.](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Installing)

That's all, folks!

This Jam leads participants through a journey of creating their very own custom digital snowglobe that can even react to device motion!


Making a Custom Digital Snowglobe



**Before you start.**: This guide takes about 30 minutes to complete. Easy Difficulty, Good start for any newbies.

What you will end up with:

![Demo](https://cloud-rcnqjs0ni-hack-club-bot.vercel.app/0image.png)

## How you will use this as a club?

As a club, you will be able to send and recieve these tokens between eachother as a way of rewarding. For example, you the club owner can send your club members 2 tokens after the end of this jam as a way to boost their enthusiasm.

This guide teaches users how to create their own personalized cryptocurrency token using Solidity and Metamask. By following the step-by-step instructions, users set up an endpoint, create a MetaMask account, and code their token on Remix Ethereum. The resulting token can be shared and used as a form of reward or gratitude among club members, fostering a sense of community and enthusiasm. The process is beginner-friendly and offers an opportunity to learn about blockchain concepts while exploring the world of cryptocurrency creation.

<dropdown title="Here are some memes to convey the message:">

![meme](https://cloud-db2kqcawa-hack-club-bot.vercel.app/77tjen8.jpg)

![meme](https://cloud-db2kqcawa-hack-club-bot.vercel.app/67tjep6.jpg)

![meme](https://cloud-db2kqcawa-hack-club-bot.vercel.app/4download__2_.jpg)

![meme](https://cloud-db2kqcawa-hack-club-bot.vercel.app/3download__3_.jpg)
</dropdown>

## Why should you even care?

* Well, imagine a reward you made that you can share withothers.
* Like a sign of gratitude or thanks. Or anything you want! This token can be like a cashback, a reward, a sign  , of thanks, a form of currency between your friends
* and well you get to learn something new
* Understanding blockchain concepts can significantly impact your future prospects, especially in the field of blockchain development.
* Learning about current trends can help you keep up and learn something new!
   
## Learning Objectives

* To learn and understand the Ethereum platform
* To create a crypto token
* Understand the basics of Solidity language

### Prerequisite knowledge required

* None! This course covers everything you need to know and get started with!
  
### Outline of the course

* Create accounts and an endpoint
* Code in solidity
* Deploy and receive the tokens.

## What to keep ready?

* install the metamask extension to your browser (a place to store your coins)
* open and keep quicknode.com ready (a place to interact with the ethereum platform)
* open and keep remix.ethereum.org ready (a place to code and deploy in solidity)

### Key Points & Terms
* MetaMask - Think of it like a bank! Metamask is a virtual wallet where you will be storing tokens through this Jam.
* Quicknode - We use this as a method to connect your metamask to the ethereum (or any) blockchain. This helps metamask or any service communicate with the network (blockchain network)
* Endpoint - This is like a connection point between any service and a blockchain network (Quicknode makes one for you making our task easier)
* Solidity - An object-oriented programming language for implementing smart contracts on various blockchain platforms, such as Ethereum.
* ERC-20 - Short for Ethereum Request for Comment 20, It helps guide the creation of new tokens in the ethereum blockchain
* Testnet - The opposite of Mainnet, Coins in the mainnet have monetary value and the value can change but in a testnet all coins are just virtual copies/duplicates without a realworld value. But dont let that get to you as these coins are indeed shareable!

<dropdown title="warnings">
#### WARNING: THE COINS YOU MAKE ARE IN THE TESTNET AND HAVE NO MONETARY VALUE! DONT EXPECT TO MAKE MONEY OUT OF THIS lol 
#### DOUBLE WARNING (AND TIP): WHEN MAKING YOUR METAMASK ACCOUNT, MAKE SURE TO SAVE THE 12 PHRASES AS THEY ARE LIKE A PASSWORD TO YOUR ACCOUNT, STORE THEM ANYWHERE SAFE LIKE YOUR NOTEPAD, DIARY, ANYWHERE SAFE. ONCE LOST, YOUR ACCOUNT IS GONE BYE-BYE FOREVER. (also dont trust anyone and show them your phrases)
</dropdown>

# The guide! (dont be overwhelmed by the number of steps, Its easy!)

## Creating A Endpoint With Quicknode

1. Navigate to quicknode.com and create an account

2. Click "Endpoints"

3. Click "Create Endpoint"

4. Click "Continue"

5. Click on "Ethereum"

6. Click on "Sepolia"

7. Choose the free version

8. Wait for the process to complete

9. Copy the HTTP link provided at the top

10. Create a MetaMask account (if you don't have one already)

11. **WARNING**: Keep the secret phrases safe and save them in a secure location

12. Open MetaMask and click on the profile button

13. Click "Add Network"

14. Scroll to the bottom and click "Add a Network Manually"

![Ss](https://cloud-es32hz2zz-hack-club-bot.vercel.app/0screenshot__74_.png)

16. Fill out the form as follows:
    - Network Name: Ethereum Sepolia
    - New RPC URL: [Paste the copied HTTP link]
    - Chain ID: 11155111
    - Currency Symbol: ETH
    - Block Explorer URL: https://sepolia.etherscan.io

17. Click "Save" or "Add" to add the network

18. Press the text showing "Account 1" to copy the MetaMask address

## Getting some free ETH for exchange fees! 🤑💲

19. Go to sepoliafaucet.com in your web browser (You're just a few clicks away from being a crypto millionaire! Well, at least in Sepolia. Time to collect those shiny tokens!)

     ![ss](https://cloud-noik0omfz-hack-club-bot.vercel.app/0screenshot__77_.png)

21. Paste the copied MetaMask address into the provided field on the Sepolia Faucet website

22. Follow the instructions on the website to claim the free tokens

## The Coding & Creation Part!

23. Go to remix.ethereum.org in your web browser (Now you're a real crypto artist! Grab your virtual paintbrush and start creating your masterpiece.)

24. Create a new file called `MyToken.sol` and add the following code:

```
// SPDX-License-Identifier: GPL-3.0

pragma solidity >=0.7.0 <0.9.0;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract MyToken is ERC20 {

    constructor () ERC20("Your Coin Name", "Your coin symbol (3-4 letters only)") {
        _mint(msg.sender, 1000000 * 10 ** decimals());
    }
}

```

![ss](https://cloud-37tpft686-hack-club-bot.vercel.app/0screenshot__80_.png)

```
Code explaination:

the first line is a comment which states the license of the code

the second line specifies the version of solidity the code is compatible with

the third line imports code from an open source library called openzeppelin

the forth line defines a new contract called MyToken from the ERC20 contract

the next few lines defines the personality of the coin like its name, symbol, amount and decimal points. psss.. BTW dont remove the " " from around your token name and symbol.
```
Quick FAQ:

<Dropdown title="Why use openzeppelin?">
      OpenZeppelin is like a prebuilt library with most of the important things already made by the community, think of it like a library used in your fav. programming language. Openzeppelin makes things easy so that we dont have to stress about the backend!
</Dropdown>

<Dropdown title="What is _mint for and why only that much?">
_mint is used to set and create an amount of tokens in the blockchain, you can increase 1000000 to any number but keep in mind that the more bigger the amount is the much less value something has. What I mean is, if everyone in the world has an Iphone, the value or the pride of having one is way low as Iphone/apple products are a way to flex but if everyone has one, you arent much unique (Dont take this example to heart as this applies to anything)
</Dropdown>

23. Click on the third icon in the sidebar to access the Solidity compiler

24. Click on "Compile MyToken.sol" and wait for the compilation to finish

25. Click on the fourth icon in the sidebar to access the Deploy tool (Deploy, deploy, and away! It's like sending your token into the crypto universe. Ready for takeoff!)

26. Click on the environment dropdown and choose "Injected provider - Metamask" (You may need to refresh the page and the name may not specifically mention MetaMask)

27. Click on "Deploy" (Waiting for confirmation? Don't worry, it's not like waiting for a pizza delivery, It wont take long!)

28. Wait for the MetaMask popup to appear and accept any prompts that show up (Buckle up, folks! You're about to embark on a digital transaction journey. Fasten your seatbelts and prepare for takeoff!)

    ![ss](https://cloud-qsv7014dp-hack-club-bot.vercel.app/0screenshot__81_.png)

30. Wait for a message or confirmation from MetaMask indicating the successful deployment

## Verifying your tokens existence (This is where you check if you did things right!)

31. Scroll down in the Deploy and Run Transactions tool to find the "Deployed Contracts" section

32. Click on the copy icon to copy the deployed contract's address

33. Go to sepolia.etherscan.io in your web browser

34. Paste the copied contract address into the search bar on Etherscan and verify its existence (Let's play detective! Paste the contract address and see if our virtual creation has left its digital footprint on the blockchain.)

    ![ss](https://cloud-jje5y5mxt-hack-club-bot.vercel.app/0screenshot__82_.png)
    ![ss](https://cloud-jje5y5mxt-hack-club-bot.vercel.app/1screenshot__83_.png)

36. Go back to MetaMask (Time to check on your tokens like a dragon guarding its treasure!)

37. Click on "Import Tokens" at the bottom of the page

38. Paste the deployed contract's address (same one used in sepolia.etherscan.io) and wait for the form to auto-complete

    ![ss](https://cloud-67bytcbnd-hack-club-bot.vercel.app/0screenshot__85_.png)

40. Continue and wait for the token to be imported

41. You will receive your coins in MetaMask (Cha-ching! It's raining digital coins in your MetaMask wallet. Time to celebrate!)

    ![ss](https://cloud-67bytcbnd-hack-club-bot.vercel.app/1screenshot__86_.png)

### Personalizing options

* Try experimenting and testing different blockchains like matic!
* Try making more coins for different occasions (maybe one for thanks and one for sorry?)
* Try messing around the settings! It wont hurt to try new things!

## How to share tokens?

* remember steps 13-17? just redo it on your reciever's (the person you want to send the tokens to) metamask
* IMPORTANT STEP - You can rename the Network name to your coins name and ** ADD YOUR (THE PERSON SENDING THE TOKEN) Quicknode http link (step 9) and paste it in the reciever's NEW RPC URL field.
* then go back your dashboard, click on your coin, click on send, paste the recievers address (step 18) to send it to him! Its that easy!!!!

  ![sending](https://cloud-ago25sz07-hack-club-bot.vercel.app/0how_to_send_tokens.gif)
  
  ![getting](https://cloud-ago25sz07-hack-club-bot.vercel.app/1recieved_tokens.gif)

### A couple of things as tips or bonus
* Make sure to give all your addresses right as messing up addresses can ruin literally everything
* Play around with code or settings to find out how things work! (You can never go wrong in a testnet)
* Before trying out a new Blockchain, do infact read and understand about it.

### Additional Resources & Guides
* Check out metaschool.so (where i learnt all of this) for many many for courses where you get to explore the wonders of Web 3.0
* Learn more about ethereum and its blockchain at - ethereum.org/en/
* Make a blockchain with python - https://hackernoon.com/learn-blockchains-by-building-one-117428612f46 & http://ecomunsing.com/build-your-own-blockchain
  
## Stuck? Facing issues? Your last braincell stopped working?

* Feel free to contact me on slack! The name's @Briyan Dyju





In this Jam, you'll be creating an awesome cryptocurrency which you will be able to personilize and share with others!


Create your own Club Crypto Currency

In this jam, you'll learn about the Mandelbrot set, and how to render it (and other fractals!) in realtime using ShaderToy.


Create INFINITE ART with MATH (and code)

Let's build a business card -- but with a twist -- it can transmit a URL on tap and light up! You'll learn the basics of designing a PCB, and you can get the cards made for free, with Hack Club's OnBoard.

Make your own PCB Hacker Card



Hello!! In this Jam, you will be designing and building a web game. When you're all done, it'll look a bit like this:
![A demonstration of a completed platformer game](https://cloud-4p2y0vzmm-hack-club-bot.vercel.app/0screen_recording_2023-08-04_at_11.06.53_am.gif)

## So how are we gonna do this?
Here are the steps we'll go through to build your own game:
1. Get started with [Glitch](https://glitch.com)
2. Start with a simple template game
3. Add more levels to the template
4. Share your game!
---
## Get set up
First, let's get started on [🎏 Glitch](https://glitch.com).
<Dropdown title="Hey, what's Glitch?">  
           Glitch is a site that makes it super simple to build web apps. You can code in your browser and see your results live.
</Dropdown>
1. Go to [glitch.com](https://glitch.com) and click `Sign Up`.
   ![Glitch.com's header, with an arrow pointing to the Sign Up button](https://cloud-ic6sx4m6w-hack-club-bot.vercel.app/0scr-20230714-psiv-3.png)
2. Choose how you'd like to sign up - you can use a GitHub account or a Google account, or if you don't have either, click `Email Magic Link` and you'll get a link and code in your email. 
3. Either click the link in the email or enter the code from the message in your browser.
4. Wahoo! You're ready to code!
---
## Start coding
Now, it's time to code!

Start by remixing my template. Head to https://glitch.com/~kaboom-game-template, then scroll down and click `Remix your own` below the preview. Now you've got your own code editor!

Before we go any further, let's take a look at the structure of a Kaboom game.
```js
kaboom()
```
Every Kaboom game's code will start with this - it initializes the library and gets everything set up. Here's what it looks like:
![A blank checkerboard canvas](https://cloud-6n8dlncke-hack-club-bot.vercel.app/0image.png)

Pretty boring. Let's get some action going!
```js
loadSprite("bean", "https://cdn.glitch.global/6e7edbfb-3679-4519-bb57-df3008b83592/bean.png?v=1688618964513")
```
This loads in a sprite so you can use it later. You pass in a name for the sprite (here, it's `bean`) and a URL. I've included a bunch of sample sprites in the project (check the `📦 Assets` tab in the sidebar!).

```js
add([ 
	sprite("bean"), 
	pos(80, 40), 
])
```
This adds a sprite to the screen. 
![The same background, but now there's a frog-bean-like sprite on it](https://cloud-65jcy7vy5-hack-club-bot.vercel.app/0image.png)

Right now, it doesn't do much. Let's change that!
```js
const bean = add([ 
	sprite("bean"), 
	pos(80, 40), 
	area(),
	body(),  
]);
```
In Kaboom, each *game object* is composed of multiple *components*. Each component will give the game object certain functionality.

> A game object is basically any character in the game, like the player character, an enemy, a rock, or a cloud.

For example, there might be a component to decide the shape of an object, whether gravity affects it, its color or even how much health it has. Let's take a deeper look at that sample:
- The `const bean` part saves the object we're making, so we can refer to it later. You don't always need to do this, but for parts you need to use again later, it's super useful.
- The `add()` method wraps all the components together, a bit like the tortilla of your object burrito. 
- `sprite("bean")` tells Kaboom "render this object with the `bean` sprite I loaded earlier". 
- `pos(80, 40)` gives it a position, at X=80, Y=40.
- `area()` gives it an area that can collide with other objects.
- `body()` gives it a physical body, which makes it affected by gravity and lets it jump.

Now, head back to your code. You'll notice I've left a comment in the code with some steps to make the game work better. Try to fill them in! If you need help with one, check below.

<Dropdown title="1. Making Bean more floaty">  
           Do you see anything that changes the world's gravity? Try changing the value there.
</Dropdown>
<Dropdown title="2. Making coins collectible">  
           You might need to look at the [Kaboom docs](https://kaboomjs.com) for this one. Take a look at the methods under `Game Obj`. What looks like it does what you want?
           For where to put it, try to find a place where _collisions_ are handled. What looks right?
</Dropdown>
<Dropdown title="3. Make the level bigger">  
           There's a place in the code where the level is laid out with symbols. Can you try to add more?
</Dropdown>
Once you're done, your game should look a bit like this:
![a screenshot of a platformer game with a wider platform and more coins](https://cloud-7rnuby5u8-hack-club-bot.vercel.app/0image.png)

> Psst.. here's a tip. Hit <kbd>F1</kbd>. See all those blue boxes? Those are the collision areas of each object in your game. Now hover over one of those objects. Now you can see every object's components! It's a bit like those [x-ray specs](https://en.wikipedia.org/wiki/X-ray_specs) that there used to be ads for in comic books, but it actually works. 
> 
> *(Did nothing happen? If you're on macOS, hold the <kbd>fn</kbd>  key as you press F1. If you're on Windows or Linux, try toggling <kbd>Fn Lock</kbd>.)*
---
## Add another level!
Now, let's add another level to our game. Find this section of the code:
```js
const levels = [
[
// Design the level layout with symbols
"@  ^ $$",
"=======",
],
// TODO add more levels
]
```
Try duplicating everything within the inner set of brackets and designing a new level! 
<Dropdown title="Done? Take a look at what it should look like.">  
	   My level looked a bit like this, but you can make yours whatever you like! Notice how I added another line to the level in order to add more stuff.
	   ```js
const levels = [
[
// Design the level layout with symbols
"@  ^ $$",
"=======",
],

[
"  $  $   ",
"@        ",
"== == ===",
],
]
```
</Dropdown>

But how does Bean get to the next level? I'll leave this as an exercise for you. 

<Dropdown title="I'm a little lost, give me some steps...">  
Here are the general steps you'll need to do in order to do this. You can pull down any of them for some guidance. (Hint: each one corresponds to about one line of code.)
<Dropdown title="1. Import a sprite to use for the goal">  
	   Go to the `📦 Assets` tab in your project and find a sprite you want to use for the goal. Click on it and choose `Copy URL`. Then find the place in the code where we load in sprites. Add your new sprite!
</Dropdown>
<Dropdown title="2. Add it to each level (except the last one)">  
	   Remember when you added some more space to the previous level? Do that again, but use a _different_ symbol.
</Dropdown>
<Dropdown title="3. Map the symbol you used to your sprite">  
	   Now take a look at the `renderNewLevel` function in the code. This function includes a dictionary of all the sprites used in each map. Go ahead and add the portal to that dictionary! 
</Dropdown>
<Dropdown title="4. Add some code to move to the next level">  
	Look at the bottom of the code. Remember when you added code to make the coin collectable? Try to copy that for the portal. When the player hits the portal: you'll want to **increase the `levelID` counter** and **render the next level**.
</Dropdown>
</Dropdown>

---
## Add more stuff!

You can also add more sprites, [some sound effects](https://kaboomjs.com/play?example=audio), or even change the look of the entire game! Check out the Kaboom [docs](https://kaboomjs.com) for documentation on how to use every feature of the library, and the [playground](https://kaboomjs.com/play) for examples! 


--- 
## Sharing your game
Now that you've made the perfect game, it's time to let others play it. Just follow these steps: (On my end, I've had issues with the "Edit project details" menu. This works a lot better for me.)
1. Click `🎏 Settings` in the top left, above the file list.
2. Click `Go to project page`
3. On that page, click `👆 Edit details`
4. Enter your new project name, then save it!
5. Click the `Edit project` button to get back to coding.

To get a link that your friends can use to play your game, click the big purple `Share` button at the top, then copy the `Live site` link.
![A screenshot of Glitch's share dialog with the "Live site" link highlighted](https://cloud-mmr3sh0b9-hack-club-bot.vercel.app/0image.png)


In this Jam, you'll be designing and creating a fun platformer-style game and sharing it with your friends.


Build a game (with explosions!)


In this jam you'll take an existing design you've made and submit it to the OnBoard repo, an open-source collection of other designs, to request your $100 manufacturing grant.

If you don't already have a design, go to [jams.hackclub.com/jam/hacker-card](https://jams.hackclub.com/jam/hacker-card) to make one!

This is a shortened version of the full [submission instructions for the grant](https://github.com/hackclub/onboard#requirements).

![](https://camo.githubusercontent.com/bd49fe87b1833c2856e8c9da45eb340b159be057e1f7ee317e36e08e8b775003/68747470733a2f2f636c6f75642d62336838316f3064662d6861636b2d636c75622d626f742e76657263656c2e6170702f306f6e626f6172645f6769746875622e706e67)

## Required Materials

- **A PCB design**: If you don't have one you can make one here: https://jams.hackclub.com/jam/hacker-card
- **A GitHub account**: If you don't have one, create one here: https://github.com/join
- **60 minutes**: It'll take a bit less time if you have experience with GitHub, but if you're new to it, it'll take a bit longer. If you don't have enough go to the time store.
- **A good time**: This one's on you~

## Star the repo (Optional)

To follow the repo for updates and show you're participating, click the "star" button on the [`hackclub/onboard`](https://github.com/hackclub/OnBoard/) repo.

![Star the OnBoard repo](https://cloud-j2h1ajlmt-hack-club-bot.vercel.app/3star-repo.png)

## 1. Join the Slack! 

Our [`#onboard`](https://hackclub.slack.com/archives/C056AMWSFKJ) channel is where the party is getting started! If you haven't already joined, make sure to add yourself to the channel. And for those who are new to the Hack Club slack, sign up to our community of 13k+ makers through [here](https://hackclub.com/slack/?event=onboard) (don't worry, there isn't an application).

Perhaps ping a little hello to `@Kevin Yang`?

## 2. Upload to JLCPCB and Take a Screenshot

Upload your Gerber files to JLCPCB.com and add them to you cart. Once completed, take a screenshot with cost included!

**Note:** Your screenshot is **VITAL** since your project cannot be approved without it. You'll include the screenshot in your PR later.

## 3. Fork!

Fork the [`onboard`](https://github.com/hackclub/OnBoard/) repo! This is the where you'll add your project files and eventually PR from!

![Fork the OnBoard repo](https://cloud-j2h1ajlmt-hack-club-bot.vercel.app/5onboard-fork.png)

## 4. Add Your Design to Your Project Repo

From your fork of `OnBoard`, create a folder with your project name under `OnBoard/projects`. To do this, go to the projects folder and click `Create new file`.

![Projects folder](https://cloud-j2h1ajlmt-hack-club-bot.vercel.app/2projects.png)

![Create new file](https://cloud-fw3ggo1g3-hack-club-bot.vercel.app/0add-file.png)

Then in the box labeled `name your file...`, type in `PROJECT_NAME/README.md`. This creates a README file under a folder called named after your project.

![Creating a folder](https://cloud-fw3ggo1g3-hack-club-bot.vercel.app/3creating-a-folder.png)

After this, copy and paste the contents of [`TEMPLATE.md`](./projects/!Template/TEMPLATE.md?plain=1) into the text editor and fill it out!

![Paste in TEMPLATE.md](https://cloud-j2h1ajlmt-hack-club-bot.vercel.app/1paste-in-template.png)

Once your done, press the big green `Commit changes` button to save!

With your README filled out, head over to add files to begin uploading your Gerber, design files, and screen shot of vendor approval.

![Upload gerber files](https://cloud-fw3ggo1g3-hack-club-bot.vercel.app/1adding-gerbers.png)

In all, you should have the following files under your project folder:
- [ ] `README.md`: A filled out [`TEMPLATE.md`](./projects/!Template/TEMPLATE.md?plain=1), renamed to `README.md`.
- [ ] `cart.png`: A screen shot of your vendor approving your board.
- [ ] `gerber.zip`: This should be the file that you send off to the vendor.
- [ ] Design files(`design.json`, `design.sch`, `design.brd`, etc) in `src` folder . Whatever format your designer outputs to should be included.
- [ ] `schematic.pdf`: A pdf of your schematic, obtained from your designer.

`cart.png`, `gerber.zip`, and `schematic.pdf` are all very important to be named EXACTLY that; all lowercase and with the correct file types. This helps our bot to know what they are.

Your files should look roughly like this:

![Ideal PR structure](https://i.imgur.com/ix7t2nJ.png)

If you have all the above, you're done with this step!

## 5. Create a PR!

Once you've uploaded your files, you can merge them to the main repo through a pull request! Under the contribute tab of your forked repo, click the big green `Open pull request`.

![Open a PR](https://cloud-j2h1ajlmt-hack-club-bot.vercel.app/0open-pr.png)

That will bring you to the main repo, where you'll initiate a pull request. All you need to do is to follow the checklist. Then, we'll review your PR, and you'll be off to the races!
![Submission checklist](https://cloud-j2h1ajlmt-hack-club-bot.vercel.app/4submission-checklist.png)


## 6. Ship it!

Post photos of your board in [`#onboard`](https://hackclub.slack.com/archives/C056AMWSFKJ)! We can't wait to see what you make!

![John sharing PCB](https://cloud-fw3ggo1g3-hack-club-bot.vercel.app/4john-sharing-pcb.png)


Get a PCB Grant


<video controls style={{width: "400px"}}> <source src="https://cloud-opkznq4e6-hack-club-bot.vercel.app/1store_preview.mp4" type="video/mp4" /></video>

[Sample Figma Design](https://www.figma.com/file/R0x2u5Z0n1wcOAbVVekcei/The-Cow-Charm?type=design&node-id=34%3A423&mode=design&t=68QuGZqGJfs2QT92-1)
[Interactive Demo](https://www.figma.com/proto/R0x2u5Z0n1wcOAbVVekcei/The-Cow-Charm?page-id=34%3A423&type=design&node-id=34-507&viewport=535%2C362%2C0.09&t=RaHKT5mf6K7wXh1B-1&scaling=scale-down&starting-point-node-id=34%3A507&mode=design)


<Dropdown title="psst">
Here's an example of what a finished product might look like! however, your project is going to be completely unique. The feel and flow of your project should be very different ;)
</Dropdown>
---

> Hacker!
> Are you awake? Hurry up; we have a boat to catch.

---

This is a Hack Club Jam that helps you create **your very own store** on the web! You'll design everything from the products you'll sell to the colors and feel of the website. In the end, you'll get a chance to pitch your design to the workshop hosts and compete for the title of <font color="#7CFC00">Best Designer</font>!

If your website looks like something you would make, you did a great job 🎉
Otherwise, go back and brainstorm ways to make your project ✨ unique ✨

Today, we'll be designing our website using [**Figma**](https://figma.com/), a design tool to create functional and awesome user interfaces! If you're worried about code, don't worry. There isn't going to be any code yet, you'll have full artistic freedom after we explain Figma's features!



There are **6** important steps in this Jam! Feel free to backtrack and reference old points as you design your dream store!

#### Outline:

1. **Embark on your journey.** (create your first Figma file)
2. **Open your inventory**. (learn about the tools in your hot bar & Figma structure)
3. **Make your first painting.** (create the landing page for your store)
4. **SO MANY DUPLICATES.** (simplify repetitive elements with components)
5. **Make it ✨ Magical ✨** (connect your pages with interactions)
6. **Your next adventure awaits...** (next steps)

Packed your things? Let's rock this.

---

## Embark on your journey. 🛶

> You made it to your home for the next hour. Time to set up camp.

### Create an Account

Head over to [figma.com](https://www.figma.com/) and create an account! Afterwards, complete the onboarding portion of registration. Select the **Free** plan, and choose "**Design with Figma**" first.

You should be instantly booted into a new design file!

![Figma New File](https://cloud-opkznq4e6-hack-club-bot.vercel.app/0figma_new_file.png)

<Dropdown title="Not there?">
If you're redirected to the dashboard instead, just click the **+ New Design File** button!
<video controls style={{width: "400px"}}> <source src="https://cloud-n2adyd9na-hack-club-bot.vercel.app/0file_from_dashboard.mp4" type="video/mp4" /></video>
</Dropdown>

If you're working with a team, click the Share button in the top right and add your groupmates' emails with "Edit" permissions!

You're all set now! ≧(´▽｀)≦

---

## Open your inventory ⚒️

<Dropdown title="A weirdly shaped creature takes off its hood">
Hey there. I'm Orpheus, your humble guide to Figma!

We're about to go over a lot of info, so don't worry if you forget some of it.
I suggest you read through this section and then use it as a cheat sheet if you ever get stuck!
</Dropdown>

It _speaks_:

Okay! So, let's go over the structure of the Figma editor.

---

![Left Sidebar](https://cloud-p4lmdd3r0-hack-club-bot.vercel.app/0pasted_image_20230716011036.png)

### Left Sidebar

Here, you'll keep track of the current objects in your design (text, shapes, images), and be able to access assets & pages (we'll go over this later).

![Toolbar](https://cloud-i2t8xhz0p-hack-club-bot.vercel.app/0pasted_image_20230716011117.png)

### Toolbar

Situated at the top of your screen, this contains every tool you need to start designing, we'll break them down below :)).

![Right Sidebar](https://cloud-i2t8xhz0p-hack-club-bot.vercel.app/1pasted_image_20230716011129.png)

### Right Sidebar

This section opens the properties of the currently selected layer or tool. You can edit attributes such as font size, stroke, etc., and prototype!

---

Figma relies on a layered system of groups. Think about it like you're stacking sheets on top of each other. Here are the main types of objects in Figma.

### Frame

The foundational element for your designs is called a "frame"! It acts like a top-level container for your content. We normally set these to the dimensions of a target device to see what our design might look like on it.

![](https://cloud-ki7xeojmd-hack-club-bot.vercel.app/0frame.gif)

### Group

A group combines related objects together. This is a temporary union that helps reduce the number of layers that you have to work with as you design.

You can group a selection of layers together with `Ctrl + G`!

![](https://cloud-8utwa7bc9-hack-club-bot.vercel.app/0group.gif)

### Layers

Layers are the building blocks in any Figma Design. They can be anything from images, vector objects, or text. Anytime you insert an image or create a rectangle, you're making a layer!

---

Let's have a quick rundown of the tools we'll be using in our design.

Your workshop host should have given you a cheat sheet for Figma's tools; this is your chance to read through it!

You can view the digital copy [here](https://cloud-brvsdgazn-hack-club-bot.vercel.app/0figma_tools.pdf)

**Phew!** That was a lot of content. Like I said earlier, feel free to come back and review :D

Hacker, it's time to make your first piece of art.

---

## Make your first painting. 🖼️

Before we start designing, we always should think about what we want to design!

Take this time to think about the name of your corporation and the products you might sell. Once you've got it, continue :D

---

Let's give your project an awesome name! Click into the area which says "Untitled" and give it a name of your choosing (you can change this at any time).

![Name your Project](https://cloud-4m7ljqmox-hack-club-bot.vercel.app/0image.png)

Next, we'll make a frame for the landing page of our website. We'll do this by clicking the hashtag-esque button on the navbar, and clicking **Desktop > Macbook Pro 16"** as our size.

<video controls style={{width: "400px"}}> <source src="https://cloud-hivp3jiyp-hack-club-bot.vercel.app/02023-07-15_21-19-10.mp4" type="video/mp4"/> </video>

Note that you can always extend the height of the frame as you need.

Can you believe it? You've created your first layer in Figma. 🎉

> I really love cows. In fact, I love them so much I'd like to make a business selling cow charms. I want to name it something unique and original. I GOT IT!
>
> ~ the cow charm ~

Inside your frame, we'll create a _text object_! Once the tool is selected, click anywhere in your frame to create a text box. You may type whatever you'd like here.

wait a minute...
![Text is too small naurr](https://cloud-6gf9bcrd6-hack-club-bot.vercel.app/0pasted_image_20230716031051.png)

What do you think we should do?

<Dropdown title="Hint">
Hmm... Think back to the tools we learned about earlier, maybe something in the "Move Tools" section?
</Dropdown>
<Dropdown title="Solution">
Luckily we can scale this up with the **Scale Tool (K)**. Scale the text to your desired size and place it where you want on the frame.

We can also select it using the **Move Tool (V)** and edit the font size in the text box's properties.
</Dropdown>

---

Let's try adding stars to our page. We can do this by selecting the **Star Tool** and placing them as we want. If a sharp grey star isn't what I want, I can choose the _Fill Color_ and the _Corner Radius_ in the layer's properties after selecting it. In fact, I can also change the number of angles and the size of each angle of the star. If you ever want to edit some property of an object, you always check the right sidebar!

> Might there be some property to smite?
> Veer your eyes to the right.

#### Quiz Time!

<Dropdown title="Try to find these properties yourself! (expand for solution)">
![Needed Properties](https://cloud-6fotdvxns-hack-club-bot.vercel.app/0pasted_image_20230716203619_480.png)
</Dropdown>

Now, I'll make the background black, text white, and change the color and size of the stars!
![Initial background](https://cloud-rh9f8bcjk-hack-club-bot.vercel.app/0pasted_image_20230718011242.png)

I want the background to resemble a dark sky with a bright moon, so I'll set it to a gradient with dark shades of purple. You can find the settings of the **Fill Color**.

![Gradient](https://cloud-rh9f8bcjk-hack-club-bot.vercel.app/1pasted_image_20230718011436.png)

It's time to create the ✨ charm ✨! I'll make a Circle with the **Ellipse Tool** and import the images I want to use for the design.

![First charm](https://cloud-rh9f8bcjk-hack-club-bot.vercel.app/2pasted_image_20230718011702.png)

It's starting to come together! It would be really awesome to have it drop down from the top of the screen, but I'm not sure how to create a string.

#### Quiz Time!

> [!question]- What tool should I use to create the string?
> We have a lot of different choices, I could use the **Line** tool to make a simple straight string, or the **Pen** tool to create a more realistic, curvy, string.
>
> I think I'll stick with the **Line** tool, thanks for your help!

This is cool, but something seems a bit off.
![String](https://cloud-rh9f8bcjk-hack-club-bot.vercel.app/3pasted_image_20230718012123.png)

There isn't a hole for the string to go through!! It would be easy to just use another circle to indicate the hole, but the gradient background makes it hard to replicate.

If only, we could cut a hole in the circle...

**WAIT NEVERMIND WE CAN YAYAYAYA**

Let's first create a circle to designate the hole, and then select both the charm and the circle destined to be a hole on top of it.

![Circle](https://cloud-rh9f8bcjk-hack-club-bot.vercel.app/4pasted_image_20230718012451.png)

At the top of your screen, you'll see an icon that looks like two overlapping rectangles; click that!

![Boolean operators](https://cloud-rh9f8bcjk-hack-club-bot.vercel.app/5pasted_image_20230718012524.png)

These are Figma's boolean operators!! 😍😍

You have four options:

1. Union selection.
   - Merges two layers together. If the objects overlap, then the shape's outline consists of it's sublayers, not including segments that overlap.
   - Think of it as a bitwise OR operator — `A | B`
2. Subtract selection.
   - Removes a layer's intersection (and itself!) from another layer. This is the opposite of a union.
   - Think of it as `A & ~B`.
3. Intersect selection.
   - Removes everything but the intersection between the two.
   - Think of it as a bitwise AND operator — `A & B`
4. Exclude selection.
   1. Keeps everything except the intersection between the two.
   2. Think of it as a bitwise XOR operator — `A ^ B`

> [!question]- Which one do we need?
> The **Subtract** boolean operator! We want to remove the smaller circle from the larger one.
>
> Awesome! Now we'll select both and perform that operation:
> ![Subtract](https://cloud-rh9f8bcjk-hack-club-bot.vercel.app/6pasted_image_20230718112359.png)

It's starting to look more and more like a charm!
![Charm](https://cloud-rh9f8bcjk-hack-club-bot.vercel.app/7pasted_image_20230718112519.png)

Now, I'll add some decorations and drop shadow, and we'll have a completed element!

![Charm with effects](https://cloud-rh9f8bcjk-hack-club-bot.vercel.app/8pasted_image_20230718112914.png)

If I have multiple layers that I want to fit into a circle, I can use Figma's **Mask** tool!
![Mask select](https://cloud-rh9f8bcjk-hack-club-bot.vercel.app/9pasted_image_20230718113841.png)
_Here, I've created a new circle to use as the frame and selected all the layers I want to be inside of it!_

This tool allows you to use a layer as a "cutout" for another, and we can even adjust it after masking!

Here's the result:
![Masked layers](https://cloud-f6y742j59-hack-club-bot.vercel.app/0pasted_image_20230718114047.png)

Now, we'll place in a product image (ill use the mockup we designed earlier).
![Background + Product](https://cloud-rgpmdor1b-hack-club-bot.vercel.app/1pasted_image_20230722221003.png)
_To make the background stars, I created 4 stars and dropped the opacity to ~60%_

From here, I can add some text using the **Text Tool (T)**, setting its fill color to whatever I want.

![With Text](https://cloud-rgpmdor1b-hack-club-bot.vercel.app/2pasted_image_20230722221229.png)

Awesome! I'll create a couple more to create a grid-like format.

![Few more!](https://cloud-rgpmdor1b-hack-club-bot.vercel.app/3pasted_image_20230722221310.png)

As you might have guessed, the footer will also be the same; we'll use a rectangle as a background:
![Step 1](https://cloud-rgpmdor1b-hack-club-bot.vercel.app/4pasted_image_20230722221404.png)

Add in star shapes with the **Star Tool** and add our logo!
![Step 2](https://cloud-rgpmdor1b-hack-club-bot.vercel.app/5pasted_image_20230722221434.png)

After that, it's up to us to add whatever information we think is necessary. I'll add a privacy & terms page and a contact us page :D

![Step 3](https://cloud-rgpmdor1b-hack-club-bot.vercel.app/6pasted_image_20230722221519.png)

Try creating the Navbar by yourself :)

---

Looks like you've got the hang of it! Remember to look back at the tool cheat sheet from earlier and start to build out your store.

Here are the pages you should build out **right now**:

1. **Landing Page** (add your own creative splash on this!)
2. **About Page**
3. **Product Listing Page** (can be on the landing page)
4. **Product Pages** (for each one you sell)

To make these, you can create separate frames for each page.

Good luck hacker! We'll see you on the other side.

---

## SO MANY DUPLICATES 😱

While you were designing your pages, you may have realized how many reused components are on each page. So, if you wanted to add an extra button or link, you had to go through every single page and edit it.

Fear not, Figma has a wonderful tool called: **Assets**!

These are layers that reference another layer instead of having its own value. If you are familiar with pointers and references, these are basically the same thing.

### Layer

![Layer Animation](https://cloud-faklou4uh-hack-club-bot.vercel.app/0color-scheme-_remix_.gif)

### Asset

![Asset Animation](https://cloud-ghmaoucif-hack-club-bot.vercel.app/0color-scheme-_remix___1_.gif)

First, we'll create a new page so that we have our final prototype in one place. We can do this by expanding the "Page" icon on the left sidebar and clicking the '+' icon when it appears. Name this page **Assets**.

Now, we'll copy over the elements that we want to turn into components.

![Copied Elements](https://cloud-e1j5bcew3-hack-club-bot.vercel.app/0pasted_image_20230717003414.png)

Now, select the entire asset, right-click, and select "**Create Component**"

![Create Component](https://cloud-e1j5bcew3-hack-club-bot.vercel.app/1pasted_image_20230717003457.png)

Do the same for every other asset you want to create. You'll know you've done it correctly if they appear purple in the left sidebar.

![Component layers](https://cloud-e1j5bcew3-hack-club-bot.vercel.app/2pasted_image_20230717003601.png)

When you open the **Assets** tab in the left sidebar, you'll get the chance to drag it into your project!

![Asset sidebar](https://cloud-e1j5bcew3-hack-club-bot.vercel.app/3pasted_image_20230717003648.png)

You did it hacker!

## Make it ✨ Magical ✨

Well, we have our pages, but it doesn't feel right. What's missing?

Right. It just feels like we're scrolling through images. Let's make this an actual prototype.

You might have noticed a **Prototype** tab in the right sidebar; this tab helps us make interactions by clicking different areas of the page.

For example, if we click an element on our **About** page, we'll get options to create an interaction.

![Prototype tab](https://cloud-e1j5bcew3-hack-club-bot.vercel.app/4pasted_image_20230717004550.png)

Let's try that!
![Interaction](https://cloud-e1j5bcew3-hack-club-bot.vercel.app/5pasted_image_20230717004607.png)

For now, we'll just use the **On Click** trigger with the **Navigate to** response. This gives us a list of frames in our project we can jump to:
![Navigate to?](https://cloud-e1j5bcew3-hack-club-bot.vercel.app/6pasted_image_20230717004656.png)

Select the one you want and customize the transition!
p.s. for similar pages (such as your product page), it might be more intuitive for a "**Smart Animate**" transition.

For example, I set the transition between the home and about page to "**Smart Animate**", and this is the result:
![Animation Preview](https://cloud-h7lkfzs4c-hack-club-bot.vercel.app/02023-07-18_11-49-28.gif)

**Follow the same technique for every single clickable element!**

---

Once you're finished, click the present icon on the top right corner (looks like a play button) and enjoy the show! Make sure you're on the final prototype page and not the assets page!

Splendid! Here are my interactions in my example design:
![Final prototype](https://cloud-e1j5bcew3-hack-club-bot.vercel.app/7pasted_image_20230717005112.png)

Hopefully, your design looks totally unique and different!

Get ready to pitch it to the hosts... 🍿

## Up for a challenge?

There's a really awesome tool in your toolbar that I haven't mentioned.
![Plugins?!](https://cloud-e1j5bcew3-hack-club-bot.vercel.app/8pasted_image_20230717005231.png)

The **Plugins** tab :00

It's a community-run store with a lot of amazing pre-made components/tools to help with your Figma design.

Feel free to browse through and find something awesome for your design. One that I thought was really cool is called "_MeshFlow Gradients_".

## Your next adventure.


If you'd like to implement this prototype into a working website, check out the jam "**Wielding the Elemental Magic of the Web (not evil)**" to figure out how to implement your design in HTML and CSS! Also, try enabling "**Dev Mode**" in Figma (a switch on the top right corner) to see property values in CSS and example code for some objects!

It's been a blast jamming out with you! Catch you later :>
<video controls style={{width: "400px"}}> <source src="https://cloud-f39p2nwab-hack-club-bot.vercel.app/00718.mp4" type="video/mp4"/> </video>
<br/>
<small>"Oh, Christmas Tree" Kevin MacLeod (incompetech.com)
Licensed under Creative Commons: By Attribution 4.0 License
http://creativecommons.org/licenses/by/4.0/</small>


In this jam, you'll be designing your own online store with Figma! In the next jam, we'll be using the Shopify API to turn this into a real store.


Design Your Own Digital Store


In this workshop, you're going to use p5.js, along with 🌟 PHYSICS 🌟, to animate colorful particles. Along the way, you'll learn a little bit about:

- how to use p5.js
- some basic physics concepts
- how _fun_ creative coding is

All of the different particles will act like planets in orbit. They'll all apply forces (gravity) to each other depending on their mass and their distance from each other. The main difference here is that they are much closer together than real planets. This is so you don't have to wait an entire year for one particle to orbit another.

When you are done with this workshop, you should end up with something similar to this!

[![Final product](https://camo.githubusercontent.com/588608bd77901d32e460818794b2832627e4a785d69bee0821115166d7be3a1b/68747470733a2f2f636c6f75642d6f64646a696971356b2e76657263656c2e6170702f3073756d6d6172792e676966)](https://camo.githubusercontent.com/588608bd77901d32e460818794b2832627e4a785d69bee0821115166d7be3a1b/68747470733a2f2f636c6f75642d6f64646a696971356b2e76657263656c2e6170702f3073756d6d6172792e676966)

This workshop should take 30-45 minutes to complete.

## Getting Set Up

First you need to setup your project. I created a basic p5.js [boilerplate](https://en.wikipedia.org/wiki/Boilerplate_code) that you can use to easily start coding.

1. Go to [https://repl.it/@SquarePear/p5-boilerplate](https://repl.it/@SquarePear/p5-boilerplate)
2. Click "fork" to make a copy for you to edit

## Making a Particle

The first step in this project is to create a class to manage the particles. Before you can do this, you should create a new file to store the class for easier readability.

1. Create a new file called `particle.js`
2. Add this file in between the `<body>` `</body>` tags of the `index.html` file:

```html
...
<body>
  <script src="particle.js"></script>
  <script src="sketch.js"></script>
</body>
...
```

3. Add the class definition to `particle.js`

```js
class Particle {}
```

A [class](https://en.wikipedia.org/wiki/Class_(computer_programming)) is just a way of connecting a set of variables and functions in one package. Now that you have a particle class, you need to define what the particle can do.

Inside your newly-created `Particle` class, add:

```js
class Particle {
  constructor (x, y, mass) {
    // Setup particle
  }

  draw() {
    // Draw particle
  }

  applyForce(force) {
    // Apply force to particle
  }

  physics(particle) {
    // Use particle
  }

  update() {
    // Update particle
  }
}
```

We just added a list of functions that objects of this class can perform. With the basic structure set up, lets go through each function individually and add the code.

```js
...
constructor(x, y, mass) {
  this.position = createVector(x, y)
  this.acceleration = createVector(0, 0)
  this.velocity = createVector(0, 0)
  this.mass = mass

  // radius = (mass / π) ** 0.5
  this.radius = Math.sqrt(this.mass / PI) * SCALE
  // set random color for particle
  this.color = color(random(0, 255), random(0, 255), random(0, 255))
}
...
```

The [constructor](https://en.wikipedia.org/wiki/Constructor_(object-oriented_programming)) is used to create an instance of a class. In this case, we use it to set up all of the variables when we make a new particle. The [`createVector()`](https://p5js.org/reference/#/p5/createVector) function is provided by p5 to easily make a [vector object](https://p5js.org/reference/#/p5.Vector). This is just a 2d line or position with a few helper functions to easily modify the values.

Next, let's add the code for drawing the particle.

```js
...
draw() {
  // Remove outline
  noStroke()
  // Set fill to particles color
  fill(this.color)
  // Draw particle
  ellipse(this.position.x, this.position.y, this.radius * 2)
}
...
```

This one is much simpler. All this function does it set the color using the [`fill()`](https://p5js.org/reference/#/p5/fill) function and then draws the particle using p5's [`ellipse()`](https://p5js.org/reference/#/p5/ellipse) function.

Next, let's add the code for applying force to the particle.

```js
...
applyForce(force) {
  // acceleration = force / mass
  this.acceleration.add(p5.Vector.div(force, this.mass))
}
...
```

Here we see the first physics formula. This calculates how much acceleration the object should have based on the force applied. We use [Newton's second law of motion](https://en.wikipedia.org/wiki/Newton%27s_laws_of_motion#Constant_Mass)—`F=ma` or `Force = mass * acceleration`— to calculate this acceleration.

Next, let's add the code for applying real-world physics to a particle.

```js
...
physics(particle) {
  // Don't apply to self
  if (this === particle) return

  // mass1 * mass2
  let mass = this.mass * particle.mass
  // radius1 + radius2
  let radius = this.radius + particle.radius
  // Distance between particles
  let distance = this.position.dist(particle.position)

  // Don't apply if particles are touching
  if (distance <= radius) return

  // force = G * mass1 * mass2 / distance ** 2
  let force = p5.Vector.sub(this.position, particle.position)
    .setMag(G * mass  / (distance ** 2))

  // Apply the force
  particle.applyForce(force)
}
...
```

This one looks complicated, but if you think about it in terms of physics it is actually surprisingly simple.

- The first line is just making sure it isn't trying to compare itself.
- Next, we declare a few variables.
- The second if statement is just used to stop the forces when the particles are colliding. This isn't 100% necessary, but things will probably break if they get too close.
- The `force` variable points from the affected particle to the affecter.
- Next the magnitude is set to the amount of force using the [gravitational formula](https://en.wikipedia.org/wiki/Newton%27s_law_of_universal_gravitation).
- Finally, the force is applied to the particle.

Finall y, let's write some code for updating the properties of the particle:

```js
...
update() {
  let deltaVelocity = p5.Vector.mult(this.acceleration, deltaTime)

  this.velocity.set(this.velocity.add(deltaVelocity))

  this.position.set(this.position.add(p5.Vector.mult(this.velocity, deltaTime)))

  this.acceleration.set(0, 0)
}
...
```

This might also look a bit intimidating at first, but if you break it down into sections it is much easier to understand.

- The first line just calculates the change in acceleration. [`deltaTime`](https://p5js.org/reference/#/p5/deltaTime) is used to keep the forces constant no matter how many frames per second you are getting.
- The next line adds the acceleration to the velocity.
- Then the velocity is added to the position, again using `deltaTime` to keep constant changes.
- Finally you reset the acceleration to zero. The velocity stays because of momentum.

Yay! You set up the Particle class! Now you can go back to the main sketch and set up the particle management.

## Managing the Particles

Open the `sketch.js` file in the left sidebar. Right now the code should look like this:

```js
function setup () {
  createCanvas(400, 400)
}

function draw () {
  background(51, 51, 51)
}
```

The [`setup()`](https://github.com/hackclub/hackclub/blob/main/workshops/particle_physics) function is run once at the beginning of the program to do any setup you might need. We use it to create the canvas using [`createCanvas()`](https://github.com/hackclub/hackclub/blob/main/workshops/particle_physics). This creates a 400x400 pixel canvas for us to draw on.

The [`draw()`](https://github.com/hackclub/hackclub/blob/main/workshops/particle_physics) function is run every frame of the program. This can be used to update the animation every frame. We will use it to perform the the physics updates and draw the particles to the canvas.

This file is where we're going to write all the program logic, from creating the `Particle`s we just wrote, to applying physics to them and animating them.

First, we will create the array of particles we will be displaying. Then we need to update and display them every frame inside `draw()`.

First, we need to set some constants and cerate an array of particles we will be displaying. Above the `setup()` function, at the beginning of the file, add:

```js
// Constants
const G = 6.67e-11
const SCALE = 0.001

// Array to store particles
let particles = []
```

In physics, `G` refers to the [Gravitational Constant](https://simple.wikipedia.org/wiki/Gravitational_constant), which is 6.67 x 10-11 N⋅m2⋅kg-2 (which we'll write as 6.67e-11 in JS). This constant is used as the basis for all sorts of fun equations.

Now, let's set up our canvas. In the `setup()` function, add:

```js
function setup() {
  createCanvas(400, 400)

  // Loop and create each particles
  for (let i = 0; i < 10; i++) {
    let x = random(0, width)
    let y = random(0, height)
    let mass = random(2e8, 1e9)

    // Add the new particle to the list
    particles.push(new Particle(x, y, mass))
  }
}
```

All we're doing in the `setup()` function is creating a random location on the canvas, as well as a random mass, for the particle. Then, we create a new `Particle` with this data and add it it to the array of particles we just created.

All of the building blocks are in place. Finally, we're going to use the `draw()` function to animate the particles we created according to the rules of physics. In the `draw()` function, add:

```js
function draw() {
  // Set the background of the canvas to a dark gray
  background(51, 51, 51)

  // Loop all particles twice
  for (const particleA of particles)
    for (const particleB of particles)
      if (particleA !== particleB) particleA.physics(particleB)

  // Loop particles again
  for (const particle of particles) {
    // Update the particle with the new acceleration and velocity
    particle.update()
    // Draw the particle on the canvas
    particle.draw()
  }
}
```

- First, we set the background of our canvas to a dark gray
- Then, we loop through the array of particles twice. If the two particles in the nested for loop are different, we use the `physics()` function we wrote earlier to apply physics to them
- After that, we loop through the array of particles again and update each `Particle` object with the new data as a result of running `physics` on the particles.
- And finally, to see the changes, we draw the particle.

We're going through this slowly and step-by-step, but don't forget that because all of thise code is in the `draw()` function, it's run dozens (sometimes hundreds) of times per second. This is how the smooth animation that you'll see in a second is created.

Here's the final sketch.js code:

## You're Finished!

Click the green "Run" button at the top of the page. You should see some colorful particles movine!

And with that, you should now have a working—although very basic—simulation of gravity between particles. This simulation is roughly what would happen in real life with these exact masses and distances. The values themselves are a bit over exaggerated to be more visually interesting.

- [Final Code](https://repl.it/@SquarePear/Particle-Physics#sketch.js)
- [Final Project](https://particle-physics.squarepear.repl.co/)

## What to Do Next?

Try changing some values and see how they affect the simulation. Add some extra features like creating a particle on click, anti-particles, or maybe apply this concept in a whole different way?

1. [Add on Click](https://repl.it/@SquarePear/Particle-Physics-Add-on-Click#sketch.js): Add a particle whenever you click on the canvas
2. [Anti-Particles](https://repl.it/@SquarePear/Particle-Physics-Anti-Particle#sketch.js): Anti-particles that repel other particles instead of attracting
3. [Physical Text](https://repl.it/@SquarePear/Particle-Physics-Text#sketch.js): Trace letters with particles


Creating a basic particle physics simulation and rendering using p5.js

Making a Basic Particle Physics Simulation


Sound visualization is one of the coolest things that modern-day web development tools have made accessible. There’s something surreal and indescribably satisfying about _seeing_ the sounds around you on your screen and somehow understanding what you’re seeing.

[![Colorful particles traveling vertically down the screen](https://camo.githubusercontent.com/ae14331c08ceff647994cdce13fb4a2247c4eca77b5f0c4ac36de966cda3c790/68747470733a2f2f636c6f75642d6d746f736c726739722d6861636b2d636c75622d626f742e76657263656c2e6170702f3266696e616c2d64656d6f2e676966)](https://camo.githubusercontent.com/ae14331c08ceff647994cdce13fb4a2247c4eca77b5f0c4ac36de966cda3c790/68747470733a2f2f636c6f75642d6d746f736c726739722d6861636b2d636c75622d626f742e76657263656c2e6170702f3266696e616c2d64656d6f2e676966)

In this workshop, you’re going to create a galaxy out of shimmering particles that expand and move based on microphone input, in less than 50 lines of code.

[Final code](https://sound-galaxy--techbug2012.repl.co/)
[Final demo](https://sound-galaxy-1.sahitid.repl.co/)

## Getting Started

We’re going to be using [p5.js](https://p5js.org/), a JavaScript library for creative coding, to make this project. This project requires two separate p5.js libraries: `p5.js` and `p5.sound.js`.

Get started from the starter project by [clicking here](https://repl.it/@TechBug2012/sound-galaxy-starter). Once your project spins up, navigate to the `index.html` file. Then, just before the end of your `<head>` tag, import these two libraries:

```html
<script src="https://cdn.jsdelivr.net/npm/p5@1.0.0/lib/p5.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/p5@1.0.0/lib/addons/p5.sound.js"></script>
```

Great! Now that we’ve imported p5, we’re ready to start writing JavaScript.

## About the Fourier Transform

At the center of everything we’re building in this workshop is something called a Fourier Transform: a mathematical operation that takes a frequency (e.g. the sound frequency picked up by your computer’s microphone) and decomposes it into the individual wavelengths that make it up. You don’t need to understand how the Fourier Transform works—it’s built into p5 and super easy to use—but if you’re interested, 3Blue1Brown made [a great video](https://youtu.be/spUNpyF58BY) explaining it.

## Setting Up p5

p5.js is primarily composed of two functions: `setup()` and `draw()`. The `setup()` function runs only once when the project first starts up, and the `draw()` function runs continuously afterwards. Let’s start by creating these two functions in your `script.js` file:

```js
function setup() {}

function draw() {}
```

Everything in p5.js happens on a p5 canvas. Let’s create a canvas that fills our window in the `setup()` function:

```js
function setup() {
  createCanvas(windowWidth, windowHeight)
  noStroke()
}
```

By default, p5 adds an outline around objects in a canvas. `noStroke()` removes this outline.

Now, let’s tell p5 to listen for microphone input.

```js
function setup() {
  createCanvas(windowWidth, windowHeight)
  noStroke()

  let mic = new p5.AudioIn()
  mic.start()
}
```

Next, let’s initialize p5’s Fast Fourier Transform algorithm. We’ll be using this throughout the project, so we want to declare it globally and initialize it in the `setup()` function:

```js
let fft

function setup() {
  createCanvas(windowWidth, windowHeight)
  noStroke()

  let mic = new p5.AudioIn()
  mic.start()

  fft = new p5.FFT()
  fft.setInput(mic)
}

function draw() {}
```

## Creating a Particle

We’re almost ready to start drawing—but as of now, we don’t have anything to draw! Let’s create a Particle object and give it some basic properties. Above the `setup()` function, add:

```js
let Particle = function (position) {}
```

This is how [objects](https://www.w3schools.com/js/js_objects.asp) are created in JavaScript. If we want to create a new Particle, we would use `let particle = new Particle()`.

We want to give the Particle object a standard set of properties that can be changed for each instance of a Particle. For now, let’s start with `position`, `speed`, and `color`—but think of some other properties that your particles can have!

```js
let Particle = function (position) {
  this.position = position
  this.speed = createVector(0, 1)
  this.color = [random(0, 255), random(0, 255), random(0, 255)]
}
```

Here, we’re setting:

- `position` to a position given to the Particle when it’s created
- `speed` to 0 in the x direction and 1 in the y direction
- `color` to a random [RGB](https://www.w3schools.com/colors/colors_rgb.asp) color.

Now that we've created our Particle object, let’s create a bunch of particles and randomly distribute them across our screen. The starter project you started with comes with a handy `galaxyManager`, which gives you a few functions to easily manage your galaxy with. The `positionParticles()` function creates an array of 1024 particles at random places on your screen. Let's add this function to the bottom of `setup()`.

```js
function setup() {
  createCanvas(windowWidth, windowHeight)
  noStroke()

  let mic = new p5.AudioIn()
  mic.start()

  fft = new p5.FFT()
  fft.setInput(mic)

  positionParticles()
}
```

## Drawing Particles

Before we can draw our particles, we need to think about what “drawing” a particle even means. As of now, a “particle” is just an abstract idea that we made up. We've given it certain properties, but we haven't used these properties anywhere.

Let’s go back to our `Particle` object and write a [method](https://www.w3schools.com/js/js_object_methods.asp) that gives instructions for drawing a particle.

```js
let Particle = function (position) {
  this.position = position
  this.speed = createVector(0, 1)
  this.color = [random(0, 255), random(0, 255), random(0, 255)]

  this.draw = function () {
    circle(this.position.x, this.position.y, this.diameter)
    fill(this.color)
  }
}
```

The `draw` method that we just added creates a circle at the `x` and `y` coordinates of the particle and fills it with the color assigned to it. Now, instead of being an abstract idea, a Particle is a randomly-colored circle.

Now, if we wanted to draw a Particle called `awesomeParticle` at the top left corner of the screen, we could do it with `awesomeParticle.draw()`.

Now that our particles are real objects, we can finally draw them on our canvas! In the p5 `draw()` function (the function under `setup()`, not the method you just created), add:

```js
function draw() {
  drawParticles()
}
```

`drawParticles()` is another function offered by the galaxy manager that calls the `draw` method on every instantiated particle.

If you run your repl now, you should see this:

[![Colorful particles randomly scattered on a white canvas](https://camo.githubusercontent.com/99375510ad5585041cb8773b1a241210216f11b31e5f3fc28552c065b2bf7999/68747470733a2f2f636c6f75642d6d746f736c726739722d6861636b2d636c75622d626f742e76657263656c2e6170702f31647261772e706e67)](https://camo.githubusercontent.com/99375510ad5585041cb8773b1a241210216f11b31e5f3fc28552c065b2bf7999/68747470733a2f2f636c6f75642d6d746f736c726739722d6861636b2d636c75622d626f742e76657263656c2e6170702f31647261772e706e67)
Nice! We've just given life to our particles! If you want to make your canvas look more like space, you can add

```js
background(0, 0, 0)
```

to your `draw()` function to make the background black.

```js
function draw() {
  background(0, 0, 0)
  drawParticles()
}
```

## Updating Particles

We have one more problem: the particles don’t move or change at all! Currently, they’re just being drawn according to the properties we gave them earlier. Let’s put the Fast Fourier Transform to use and make our particles update according to the microphone input.

Just like for drawing particles, we need to set instructions for what “updating” a particle means via a method. Under the `draw` method in the `Particle` object, add

```js
this.update = function (energy) {}
```

We’re passing in an `energy`, which is the intensity of sound at each part of the FFT spectrum. In our case, this means the intensity of each particle.

There are endless ways to update a particle based on intensity of sound, but here’s what I personally came up with:

```js
this.update = function (energy) {
  this.diameter = random(5, 7) + energy * 100
  this.position.y += this.speed.y * energy * 10
  if (this.position.y > height) {
    this.position.y = 0
  }
}
```

This makes the particles shimmer (like stars in a galaxy), updates the diameter and speed based on sound intensity, and resets each particle to the top of the screen once they reach the bottom of the screen to make it look like a continuous stream of particles.

This is where you shine! Play around with these numbers, think of other ways to update the particles—don’t walk out of this meeting with this block of code unchanged!

Now that we’ve given instructions for updating a particle, we can finally put the Fast Fourier Transform to use and continuously draw updated particles! In the `draw()` function, remove `drawParticles()` and replace it with these two lines:

```js
let spectrum = fft.analyze()
updateParticles(spectrum)
```

This runs p5’s Fast Fourier Transform algorithm and updates each particle accordingly using another handy function from the galaxy manager.

Congratulations! You did it! Here’s what your entire `script.js` file should now look like:

```js
let fft

let Particle = function (position) {
  this.position = position
  this.speed = createVector(0, 1)
  this.color = [random(0, 255), random(0, 255), random(0, 255)]
  this.draw = function () {
    circle(this.position.x, this.position.y, this.diameter)
    fill(this.color)
  }
  this.update = function (energy) {
    this.position.y += this.speed.y * energy * 10
    if (this.position.y > height) {
      this.position.y = 0
    }
    this.diameter = random(5, 7) + energy * 100
  }
}

function setup() {
  createCanvas(windowWidth, windowHeight)
  noStroke()

  let mic = new p5.AudioIn()
  mic.start()

  fft = new p5.FFT()
  fft.setInput(mic)

  positionParticles()
}

function draw() {
  background(0, 0, 0)
  let spectrum = fft.analyze()
  updateParticles(spectrum)
}
```

Run your repl now, then **open it in a new window** by clicking the window button at the top right corner. Make sure the page has access to your microphone, then click once on the screen. You should start seeing a shimmering galaxy that you can control with your voice!

## Hacking

There are endless ways to make this project completely your own! Go back through your code and look for anything that can be played with. Try changing the default values of your Particles, playing with the numbers in the `update` method, and think of ways you can add to this to make it even better!

Here are some examples of projects that stem from this project but take it even further:

- **Raining particles**: [Demo](https://observant-wild-sunspot.glitch.me/) [Code](https://glitch.com/edit/#!/observant-wild-sunspot)
- **Raining particles 2**: [Demo](https://icy-married-crabapple.glitch.me/) [Code](https://glitch.com/edit/#!/icy-married-crabapple)
- **Using mp3 files as input**: [Demo](https://sound-viz-song-2--techbug2012.repl.co/) [Code](https://repl.it/@TechBug2012/sound-viz-song-2)

Visualize sound by making particles move in a galaxy!

Create Your Own Space-Themed Audio Visualizer


_Note: this workshop requires Google Chrome or another browser [supporting the Web Speech API](https://caniuse.com/mdn-api_speechrecognition)._

We’ll be using [p5.js](https://p5js.org/) & the p5.speech library to make something fun with web speech recognition! Say a color name out loud, & the screen will fill with that color.

[**Live demo**](https://speak-colors.glitch.me/)  
[**Final code**](https://glitch.com/edit/#!/speak-colors)

## Setup

First, let’s make a new HTML project on [repl.it](https://repl.it/): [start one right here](https://repl.it/languages/html).

Next, we need to import the p5 & p5.speech libraries. Because these are long URLs, just replace the file with this:

```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Speak a Color</title>
    <script src="https://cdn.jsdelivr.net/npm/p5@1.0.0/lib/p5.min.js"></script>
    <script src="https://rawcdn.githack.com/IDMNYU/p5.js-speech/e7ae007d61f048fc2379971b0de7d5db8abb7eee/lib/p5.speech.js"></script>
  </head>
  <body>
    <script src="script.js"></script>
  </body>
</html>
```

But never copy & paste code without reading it 🙂

- We’re initializing an HTML page
- We’re giving it a `<title>`, which appears as the tab name in your browser
- We’re linking the two external libraries we need
- Finally, a link to the `script.js` file we’ll write our own JavaScript code in

The rest of the code samples in this workshop will all be for `script.js`, where we write the p5 code.

## Displaying instructions

First, we need to set up a canvas with p5.

- We want the canvas to fill the screen, so p5's `windowWidth` & `windowHeight` come in handy.
- Let’s go ahead & fill the background with white, and make the text color dark grey.

```js
function setup() {
  createCanvas(windowWidth, windowHeight)
  background(255)
  fill(25)
}
```

The page still looks empty, oops! Let’s add some initial instructions, even though they won’t do anything yet.

(You only need the `text()` line here—you can omit the `textSize`, `textAlign` etc—but these other lines make the text more fun-looking. Feel free to change the size or font!)

```js
function setup() {
  createCanvas(windowWidth, windowWidth)
  background(255)
  fill(25)

  textSize(48)
  textAlign(CENTER)
  textStyle(BOLDITALIC)
  textFont('"Avenir Next", system-ui, sans-serif')
  text('SAY A COLOR', width / 2, height / 2)
}
```

Fantastic! Up next: the speech recognition we came here for.

## Running speech recognition

The p5.speech library has [an example](https://github.com/IDMNYU/p5.js-speech/blob/master/examples/05continuousrecognition.html) of "continuous" speech recognition—that is, the mic stays active after you’ve said your first phrase, instead of being one-time.

Let’s set up continuous speech recognition, and display an alert when new speech is transcribed:

```js
const speech = new p5.SpeechRec('en-US', parseResult)
speech.continuous = true
speech.interimResults = false

function setup() {
  // …
  text('SAY A COLOR', width / 2, height / 2)
  speech.start()
}

function draw() {
  // Where we’re going we don’t need drawing
}

function parseResult() {
  if (speech.resultValue) {
    alert(speech.resultString)
  }
}
```

We’re getting there…

## Changing the color

Because HTML/CSS support a wide array of [named colors](https://html-color-codes.info/color-names/), we’re going to use those for this project. (You can read more about [where the color names come from](https://www.chenhuijing.com/blog/where-did-css-named-colours-come-from/), or if you want to extend this project, figure out how to use [JavaScript objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) to support your own colors!)

For the first iteration, we’re just supporting single-word colors, because it’s simplest.

- We’re starting with the `speech.resultString`, which we used before.
- To get the last word:
    - We’ll do [`.split(' ')`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split), which converts the text into a [JavaScript array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) of words: `'hello there friend'.split(' ')` is `['hello', 'there', 'friend']`
    - `.pop()` then gets the last item from the array, which is the last word as a string
- Finally, because we want all text on the site to be in all-caps, we’ll add `.toUpperCase()`
- These function calls can all be chained next to each other!

```js
// …
function parseResult() {
  if (speech.resultValue) {
    alert(speech.resultString.split(' ').pop().toUpperCase())
  }
}
```

Spectacular! Now let’s set the background color to the color, and write it onscreen.

```js
// …
function parseResult() {
  if (speech.resultValue) {
    const color = speech.resultString.split(' ').pop().toUpperCase()
    background(color)
    text(color, width / 2, height / 2)
    console.log(color)
  }
}
```

- Because we need to use the color name in multiple places, we’re setting it to a variable, so that we don’t have to do the whole split/pop/upperCase things multiple times.
- Setting the background is as simple as `background(color)`. Thanks, p5!
- Adding the text onscreen works just the way the instructions did. Because we want it centered horizontally & vertically, we set the x coordinate to `width / 2` (so the midpoint of the width of the canvas), & the y to `height / 2` (same for canvas height).
- The `console.log` line is totally optional, but it allows you to see what’s being transcribed in your [DevTools JavaScript console](https://developers.google.com/web/tools/chrome-devtools/console/log).

## Wrapping up

That’s it! Here’s the whole `script.js` file:

```js
const speech = new p5.SpeechRec('en-US', parseResult)
speech.continuous = true
speech.interimResults = false

function setup() {
  createCanvas(windowWidth, windowHeight)
  background(255)
  fill(25)

  textSize(48)
  textAlign(CENTER)
  textStyle(BOLDITALIC)
  textFont('"Avenir Next", system-ui, sans-serif')
  text('SAY A COLOR', width / 2, height / 2)
  speech.start()
}

function draw() {
  // Where we’re going we don’t need drawing
}

function parseResult() {
  if (speech.resultValue) {
    const color = speech.resultString.split(' ').pop().toUpperCase()
    background(color)
    text(color, width / 2, height / 2)
    console.log(color)
  }
}
```

A few ideas to take this further:

- Support multi-word color names. Hint: instead of getting the last word, maybe figure out how to remove the spaces?
- As aforementioned, support your own colors 👀
- Keep track of all the colors, maybe show them all simultaneously?

Color your screen with your voice via speech recognition.

Speak & Color Your Screen Outloud


One of the most common myths about coding among people who are first learning to code is that coding mostly consists of sitting in a dark room all day writing algorithms in a black terminal window with green text, solving complex mathematical equations, and generally being a genius.

You’re going to crush this myth in this workshop by making crazy, colorful splatter paint right in your web browser, in only 20 minutes.

![Colorful patterns of dots and lines on a canvas](https://cloud-3aosybiuc-hack-club-bot.vercel.app/1final-demo.png)

[Final code](https://repl.it/@TechBug2012/splatter-paint#index.html)
[Final demo](https://splatter-paint.techbug2012.repl.co)

## Getting started

Start by creating a new HTML project on repl.it by going to [repl.it/languages/html](https://repl.it/languages/html).

We’re going to be using a library called [Paper.js](http://paperjs.org), which makes it easy to create cool visuals on an [HTML canvas](https://www.w3schools.com/html/html5_canvas.asp).

To import a JavaScript library in HTML, we use the `<script>` tag and include a link to the library we want to import. For Paper.js, this looks like:

```html
<script src="https://unpkg.com/paper@0.11.5/dist/paper-full.min.js"></script>
```

Add a script tag that imports Paper.js somewhere in the `<head>`. Then, directly under it, add the following:

```html
<script
  type="text/paperscript"
  canvas="splatterPaint"
  src="/script.js"
></script>
```

Let’s go over what each attribute of this tag does:

1. `type="text/paperscript"` tells Paper.js that the code in the script is Paper.js code
2. `canvas="splatterPaint"` refers to the ID of the HTML canvas that Paper.js will operate on (we haven’t created this canvas yet, but we will in a second)
3. `src="/script.js"` means that the content of this script is located in your `script.js` file

Remember when we referred to a canvas called `splatterPaint` that hasn’t been created yet? Let’s create that canvas. In the `<body>`, remove the line that imports `script.js` and replace it with

```html
<canvas id="splatterPaint"></canvas>
```

Amazing! we’ve got ourselves a canvas.

## Drawing some circles

Now that we’ve successfully imported Paper.js and created a canvas to work on, it’s time to write the JavaScript code that will create our splatter paint.

Let’s write a function that draws a circle at the cursor’s position whenever the mouse is moved.

Navigate to your `script.js` file and create a function called `onMouseMove`:

```js
function onMouseMove(event) {}
```

Although you can normally call functions whatever you want, it’s important that this function is called `onMouseMove` and passes in an `event`. Paper.js knows what `onMouseMove` is—when it sees this function, it will know to run the code you write inside it every time your mouse moves, and that the `event` you pass in is a [Paper.js Mouse Event](https://paperjs.org/reference/mouseevent/). Cool, right?

Time to draw our circle! Inside the function you just created, add this code snippet, which creates a circle at the mouse cursor with a radius of 10px:

```js
var path = new Path.Circle({
  center: event.middlePoint,
  radius: 10
})
```

If you run your repl now and move your mouse around, you’ll see...nothing. You are, in fact, drawing circles, but the circles are currently transparent. So, let’s give them some color. Under the previous code snippet, still in the `onMouseMove` function, add:

```js
path.fillColor = {
  hue: 0,
  saturation: 1,
  brightness: 1
}
```

Right now, your entire `script.js` file should look like this:

```js
function onMouseMove(event) {
  var path = new Path.Circle({
    center: event.middlePoint,
    radius: 10
  })
  path.fillColor = {
    hue: 0,
    saturation: 1,
    brightness: 1
  }
}
```

Instead of using the more common hexademical or RGB color systems, Paper.js uses the HSB color system, which uses angles on a color wheel to describe color. In the HSB color system, 0 = 0° = red, and `360*n`° is also red.

![Color wheel in which each color is assigned a degree value](https://cloud-b0scmt0cu-hack-club-bot.vercel.app/0hsb-color-wheel.png)

(If you’re interested in learning more about the HSB color system, check out [this fantastic explanation](https://learnui.design/blog/the-hsb-color-system-practicioners-primer.html))

With this in mind, try running your repl now. Because you set `hue` to 0, you’re now drawing red circles! But your circles only appear in the top left corner of the screen. That’s because the width and height of your canvas are currently set to the Paper.js defaults (300px by 150px).

Let’s make your canvas fill the whole screen. In your `style.css` file, add the following:

```css
canvas {
  width: 100%;
  height: 100%;
}
```

Run your repl again.

Almost there. The CSS you just wrote set the canvas width and height to 100% of the parent element. In your `index.html` file, `<body>` is parent element of the `<canvas>` because you created the canvas in between the `<body>` tags.

`<body>` is currently as big as its own parent element, `<html>`, which doesn’t quite fill the whole screen. With this in mind, add the following to your CSS file:

```css
html,
body {
  width: 100%;
  height: 100%;
  margin: 0;
}
```

This sets the width and height of the body to the width and height of your screen, and removes any extra space between the edge of your screen and the body.

Just to recap: your entire CSS file should now look like this:

```css
html,
body {
  width: 100%;
  height: 100%;
  margin: 0;
}
canvas {
  width: 100%;
  height: 100%;
}
```

If you run your repl again, you should notice that your red circles are now filling the entire screen!

![Random pattern formed by red circles](https://cloud-3aosybiuc-hack-club-bot.vercel.app/6red-circles.jpg)

## Making it Splattery

We’re getting somewhere, but this still doesn’t feel very splattery.

![colorful paint randomly splattered on a canvas](https://cloud-3aosybiuc-hack-club-bot.vercel.app/5real-splatter-paint.jpg)

Part of what makes splatter paint so fun to create and look at is the chaotic randomness of everything on the canvas. So, if you want to get your website as close to splatter paint as possible, the best way to do it is to introduce some randomness.

Change the radius of your circles from `10` to `Math.round(Math.random() * 25) + 5`. This makes the radius a random number between 5 and 30. Then run the repl again.

![Circles with large radii forming a random pattern on a canvas](https://cloud-3aosybiuc-hack-club-bot.vercel.app/4random-radius.jpg)

Not bad, but it feels sort of mashed together, doesn’t it? Maybe we can make each circle unique by making it a different color than the last. Try changing the hue from `0` to `event.count * 3`. Run the repl and see what happens.

![Rainbow assortment of circles of various sizes on a canvas](https://cloud-3aosybiuc-hack-club-bot.vercel.app/3rainbow-colors.jpg)

`event.count * 3` creates a rainbow effect by setting the hue on each circle to the total number of times a circle has been drawn multiplied by 3, which jumps around the HSB color wheel. And it looks great!

Congratulations! You can now splatter colorful circles all over your screen. If you haven’t already, open your repl in a new tab and treat yourself to a bigger canvas to go crazy on.

## Hacking

Your journey is far from over. There are endless directions you can take this project in. Here are a few suggestions.

1. If you want to increase the distance between each circle, you can add `tool.fixedDistance = SOME_NUMBER` to the top of your `script.js` file. This will fire the event after your cursor has moved every `SOME_NUMBER` px instead of every time your mouse moves. You can set it to fixed number, or you can make it random!
2. If you find the rainbows too predictable, you can set the hue to a random number between 0 and 360 (remember, this covers every color on the HSB system).
3. Who says your canvas has to be white? Try setting the background color of your website to something custom—your favorite color, an image, or even a [gradient](https://developer.mozilla.org/en-US/docs/Web/CSS/linear-gradient)—and/or change it every time a new circle is created.
4. Who says you have to draw circles? Try drawing a random mix of circles, ovals of random lengths and widths, and other shapes.
5. Randomness is fun, but controlled randomness is even more fun. Take a look at the [Paper.js docs on mouse events](https://paperjs.org/reference/mouseevent/). How can you use the properties of the MouseEvent to play with the radius? (here’s what I came up with: try setting the radius to `event.delta.length` and see what happens)
6. If you want to hurt your eyes and ears, try using the [Tone.js](https://tonejs.github.io) library to play a synth sound of a random frequency whenever a new circle is created.

Here are some example projects that have stemmed from this project:

- [https://welllitvelvetyoperation.techbug2012.repl.co](https://welllitvelvetyoperation.techbug2012.repl.co)
- [https://splatter-paint-crazy.techbug2012.repl.co](https://splatter-paint-crazy.techbug2012.repl.co) (**WARNING: FLASHY COLORS**)
- [https://wlhc-paperjs-demo-custom1.glitch.me](https://wlhc-paperjs-demo-custom1.glitch.me)

Now, your task is to spend the rest of the meeting making this project insanely cool and totally unique!

Crazy colorful splatter paint in your browser with Paper.js


Splatter Paint in Your Browser

Whether you have programmed your whole life or this is your very first project, there is plenty of fun to be had with creating a  Choose Your Own Adventure Game (CYOA)! This build incorporates music, interactive elements, and the ability to control all stylistic  features! The most important part is to use your imagination since there is no limit to what YOU can create!


Crafting a Build Your Own Adventure Game!


![](https://i.ibb.co/p0LHv5g/Slide-16-9-1.png)

# Setup
Fork the [starter code](https://stackblitz.com/edit/vitejs-vite-eiq9ch?file=src%2FApp.tsx).

_Optional_: Create a StackBlitz account to save your work.

# The Basics
**Draggable** - something that can be dragged within droppables

**Droppable** - something that can hold draggables

We are going to be using [hello-pangea/dnd](https://github.com/hello-pangea/dnd) to help us with dragging and dropping since it provides a nice, easy-to-use abstraction.


# Part 1: Creating a Draggable
We want to create our key components. The `DataCard` represents each object within the tier-list.

![](https://i.ibb.co/PtVn0NT/image.png)
First, navigate to **components/DataCard.tsx**.
We want to import `Draggable` from `@hello-pangea/dnd` and then define the arguments our component will take.
```tsx
import { Draggable } from '@hello-pangea/dnd'

interface DataCardProps {
    id: string // this is a unique identifier -- so we know what's getting dragged!
    index: number // this is the item's position within the tier
    imageUrl: string // this is the image!
}
```

After this, we can define our component.
```tsx
import { Draggable } from '@hello-pangea/dnd'

interface DataCardProps {
    id: string // this is a unique identifier -- so we know what's getting dragged!
    index: number // this is the item's position within the tier
    imageUrl: string // this is the image!
}

export default function DataCard({ id, index, imageUrl }: DataCardProps) {
    //
}
```

Within this, we can return our draggable `DataCard`. To create a draggable, you need to use the `Draggable` component from `@hello-pangea/dnd`. The child element will be a function which gives the needed references and props to be able to have a draggable. That function will return the Draggable's content. 
```tsx
import { Draggable } from '@hello-pangea/dnd';

interface DataCardProps {
    id: string;
    index: number;
    imageUrl: string;
}

export default function DataCard({ id, index, imageUrl }: DataCardProps) {
    return (
        <Draggable draggableId={id} index={index}>
            {(provided) => (
                <div
                    ref={provided.innerRef}
                    {...provided.draggableProps}
                    {...provided.dragHandleProps}
                >
                    <img className="w-16" src={imageUrl} />
                </div>
            )}
        </Draggable>
    );
}
```

# Part 2: Create a Droppable
Each tier has a droppable area where items can be moved around!
![](https://i.ibb.co/dbMNn4D/image.png)

In this section, we are creating a droppable container! Within that container, we are also showing the tier's items.
First, navigate to **components/Tier.tsx**.

Let's define the props as well as component. We will also show the name of the tier.
```tsx
import { Droppable } from '@hello-pangea/dnd';
import DataCard from './DataCard';

interface TierProps {
    name: string
    data: { id: string, imageUrl: string }[]
    className?: string
}

export default function Tier({ name, data, className = '' }: TierProps) {
    return (
        <div className="flex">
            <div className={'w-32 py-8 text-center ' + className}>{ name }</div>

        </div>
    )
}
```

After this, we can start creating our droppable. Also, we will put our data into their respective tiers.

```tsx
import { Droppable } from '@hello-pangea/dnd';
import DataCard from './DataCard';

interface TierProps {
    name: string
    data: { id: string, imageUrl: string }[]
    className?: string
}

export default function Tier({ name, data, className = '' }: TierProps) {
    return (
        <div className="flex">
            <div className={'w-32 py-8 text-center ' + className}>{ name }</div>

            <Droppable droppableId={name} direction="horizontal">
                {(provided) => (
                    <div
                        className="pl-4 flex flex-wrap items-center gap-4 border w-full select-none"
                        ref={provided.innerRef}
                        {...provided.droppableProps}
                    >
                        {data.map((data, index) => (
                            <DataCard
                                key={data.id}
                                id={data.id}
                                index={index}
                                imageUrl={data.imageUrl}
                            />
                        ))}
                        {provided.placeholder}
                    </div>
                )}
            </Droppable>
        </div>
    )
}
```

Droppable, similar to draggable, also requires a child function that returns the content. In this case, it would be the various DataCards from each element of `data`. In the 4th section, we'll go over how to customize this data.

# Part 3: Create the Tier List
Let's put all the previous parts together. In this part, simply map the different tiers from the `tiers` variable into `Tier` components.

**App.tsx**
```tsx
import { DragDropContext, DropResult } from '@hello-pangea/dnd';
import Tier from './components/Tier';
import { useTierState } from './useTierState';
import { arrayMove, arrayTransfer } from './helpers';

export default function App() {
    const [tiers, setTiers] = useTierState();

    function onDragEnd(result: DropResult) {
        // We will implement this together in the 5th part!
    }

    return (
        <DragDropContext onDragEnd={onDragEnd}>
            <div>
                {tiers.map((tier) => (
                    <Tier
                        key={tier.name}
                        className={tier.className}
                        name={tier.name}
                        data={tier.data}
                    />
                ))}
            </div>
        </DragDropContext>
    );
}
```

# Part 4: Customize Tier List!
If you run the site, you'll notice that there are already items in the tier list. However, we can customize this to whatever you want!

In the `useTierState.ts` file, you'll notice how each tier is defined. Each tier has a name, data, and a className.

Here's what you need to know:
- the tier name must be unique
- the className will only be applied to the box with the tier name
- for each item, the id must be unique

To customize your tier list, simply change the data within the unranked tier. **Tip**: You can drag and drop images into your project's `public` directory, or you can provide a direct link to the image.

Here's an example:
```
[
    {
        id: '1', imageUrl: 'https://i.ibb.co/DRd2Fg4/image.png',
    },
    {
        id: '2', imageUrl: 'my_image.png'
    }
]
```

# Part 5: Implementing onDragEnd
First, this function takes one argument, which is of type `DropResult`. This contains all the "context" of the event. For example, the draggable being dragged or the droppable which it's getting dragged to.

There are a couple cases we want to handle.
1. If the item (draggable) is not being moved to a tier (droppable).
2. If the item is being moved within the tier.
3. If the item is being moved between tiers.

Let's set that up:
```ts
function onDragEnd(result: DropResult) {
    if (!result.destination) return // we can't do anything if the item isn't being dragged into/within a tier

    const oldIndex = result.source.index // this is the original position of the item
    const newIndex = result.destination.index // this is the new position of the item
    const oldTierName = result.source.droppableId // this is the original tier of the item
    const newTierName = result.destination.droppableId // this is the new tier of the item

    if (oldTierName === newTierName) {
        // this means the item is being moved within the current tier
    } else {
        // this means the item is being moved to another tier
    }
}
```

Now, if the item is moved within the tier, we simply have to move the item within that tier's array of data. If the item is moved to another tier, we remove it from the old tier and add it to the new tier.

Here's how that looks like:
```ts
function onDragEnd(result: DropResult) {
    if (!result.destination) return;

    const oldIndex = result.source.index;
    const newIndex = result.destination.index;
    const oldTierName = result.source.droppableId;
    const newTierName = result.destination.droppableId;
    
    if (oldTierName === newTierName)
        setTiers((prevTiers) => {
            const tier = prevTiers.find(
                (tier) => tier.name === oldTierName
            )!;
            
            arrayMove(tier.data, oldIndex, newIndex); // I've implemented this helper function for you!
            
            return prevTiers;
        });
    else
        setTiers((prevTiers) => {
            const oldTier = prevTiers.find(
                (tier) => tier.name === oldTierName
            )!;
            const newTier = prevTiers.find(
                (tier) => tier.name === newTierName
            )!;
            
            arrayTransfer(oldTier.data, newTier.data, oldIndex, newIndex); // I've implemented this helper function for you!
            
            return prevTiers
        });
}
```

# Final Code Example
https://stackblitz.com/edit/vitejs-vite-dpvrzw?file=README.md


Create Your Own Tier List In React

In this Jam, you'll be creating an awesome unique Lofi Animation using Voxels! It will be a lot of fun and you will have an awesome animation as a result!


Creating Your Own 3D Club Lofi Animation

In this jam, we'll be using ChatGPT to generate the text of a children's comic, and use Stable Diffusion to create pictures for the comic. Both ChatGPT and Stable Diffusion are completely free. Lastly, we'll walk through deploying your comic as a website (yes, with a live URL :)) so you can share it with your friends 🌎


Create Your Own Comic Book with AI

![https://cloud-4vl3zrzew-hack-club-bot.vercel.app/7image.gif](https://cloud-4vl3zrzew-hack-club-bot.vercel.app/7image.gif)

Imagine a universe where you hold the magic to create your own dimensions and craft the castles of your dreams. **Today, we'll embark on a journey through the heart of VR development by constructing our very own floating virtual lands and join forces by integrating them into a shared celestial town.**

## Objective

In this workshop, we'll not only dive into the futuristic world of Augmented Reality (AR) but we're going one step further, summoning not one, but multiple interactive 3D models to our web-based AR application. Because if you can make one duck appear, why not a whole duck army?

## Prerequisites

You should have a basic understanding of HTML, CSS, and JavaScript. If you can say "Hello, World!" in these languages, you're ready to conquer the AR world.

![https://cloud-4vl3zrzew-hack-club-bot.vercel.app/6image__1_.gif](https://cloud-4vl3zrzew-hack-club-bot.vercel.app/6image__1_.gif)

## Tools

- HTML, CSS, JavaScript - The holy trinity of web development.
- AR.js and A-Frame libraries - Our magic AR wand.
- Any text editor - Even Notepad is invited to this party!
- Any modern web browser - Yes, even Internet Explorer... if you dare.

## Getting Started

1. Head over to [Argument Reality Template](https://replit.com/@DevIos01/WebBasedArgumentReality-Template) and click "fork". Then, sign up or sign in, which will load the new dashboard where you can do everything.

![Gif of how to fork the project](https://cloud-4vl3zrzew-hack-club-bot.vercel.app/5ar__1_.gif)


1. Take a moment to look around and familiarize yourself with this lovely dashboard.

![image (19).png](https://cloud-4vl3zrzew-hack-club-bot.vercel.app/4image__19___1_.png)

**Source Code:** The canvas where all your creativity takes the form of code.

- Type in your desired code, using the provided programming language syntax.
- Lines are numbered for easy tracking and debugging.
- Syntax is color-coded for readability and error prevention.

**Toolbar:** Actions for coding and executing scripts.

- Press "Run" to execute your current script.
- Press "Version control" to manage your coding versions.

**Left sidebar:** File explorer, list of all files in the current workspace.

- Click on a filename to open it in the editor.
- Right-click a file for more options like rename, move, delete, and more.

**Right sidebar:** Debug console, shows the output of your executed scripts.

- Use the "Clear" button to clear the console.

### Important controls:

- **New File:** **`Ctrl`** + **`N`**
- **Save File:** **`Ctrl`** + **`S`**
- **Find:** **`Ctrl`** + **`F`**
- **Replace:** **`Ctrl`** + **`H`**
- **Comment/Uncomment:** **`Ctrl`** + **`/`**
- **Indent:** **`Tab`**
- **Outdent:** **`Shift`** + **`Tab`**
- **Delete:** **`Ctrl`** + **`D`**
- **Go to line:** **`Ctrl`** + **`G`**
- **Autocomplete:** **`Ctrl`** + **`Space`**

![https://cloud-4vl3zrzew-hack-club-bot.vercel.app/3image__2_.gif](https://cloud-4vl3zrzew-hack-club-bot.vercel.app/3image__2_.gif)

Steps

### 1. Setting Up

Picture this - you're a wizard, and you're about to cast your first spell. You reach out for your wand and your spell book, right? Similarly, in the realm of AR, our HTML document is our spell book and the JavaScript files are our magic wands!

```html
<!DOCTYPE html>
<html>
  <head>
      
  <script src="https://aframe.io/releases/1.0.4/aframe.min.js"></script>
  <script src="https://raw.githack.com/AR-js-org/AR.js/master/aframe/build/aframe-ar.js"></script>
  <script src="https://raw.githack.com/donmccurdy/aframe-extras/master/dist/aframe-extras.loaders.min.js"></script>
  <script
    src="https://raw.githack.com/AR-js-org/studio-backend/master/src/modules/marker/tools/gesture-detector.js"></script>
  <script
    src="https://raw.githack.com/AR-js-org/studio-backend/master/src/modules/marker/tools/gesture-handler.js"></script>
</head>
<body style='margin : 0px; overflow: hidden;'>
  
</body>
</html>

```

![https://cloud-4vl3zrzew-hack-club-bot.vercel.app/2image__3_.gif](https://cloud-4vl3zrzew-hack-club-bot.vercel.app/2image__3_.gif)

We're essentially incorporating these 'spells' into our web page to breathe interactivity into it. Without them, our web page would be a static set. But with JS (our magic ink), we make the elements come alive, move, disappear, change colors, and much more!

Now, we've prepared our magical stage. It's invisible for now, but we're just getting started. Hold onto your wizard hats as we dive deeper into the mystical world of AR!

### 2. Unveiling the AR Scene

Now that we've prepared our magical spell book, it's time to set the stage for the grand performance! Imagine you're a magician, and you want to conjure a magical creature for your audience. In our digital magic show, that creature is a 3D duck.🦆✨

**The Magical Treasure Chest**

First, we need a place to store our magical entities, our 3D models.

```html
    <a-assets>
      <a-asset-item id="animated-asset" src="demo.gltf"></a-asset-item>
    </a-assets>
```

This is our magical treasure chest, holding our precious 3D duck.

**The Magic Circle**

Next, we draw our magic circle. Whenever someone activates this circle (using a specific marker), our magic comes to life!

```html
    <a-marker id="animated-marker" type="pattern" preset="custom" url="marker.patt" raycaster="objects: .clickable"
      emitevents="true" cursor="fuse: false; rayOrigin: mouse;" id="markerA">
      <a-entity id="bowser-model" scale="0.4 0.4 0.4" animation-mixer="loop: repeat" gltf-model="#animated-asset"
        class="clickable" gesture-handler></a-entity>
    </a-marker>
```

**The Magician's Eye**

Every magician needs a way to see and interact with his audience. That's what the magical camera is for:

```html
    <a-entity camera></a-entity>
```

With the cursor, we can point, choose, and interact, just as a magician might use a wand!

**The Magical Scroll**

Lastly, the magician leaves a message, guiding the audience on how to partake in the magic:

```html
<a-text value="Please point your camera at the custom HackClub marker." align="center" position="0 -0.5 -1.5"
      color="red" visible="true"></a-text>
```

![https://cloud-4vl3zrzew-hack-club-bot.vercel.app/1image__4_.gif](https://cloud-4vl3zrzew-hack-club-bot.vercel.app/1image__4_.gif)

When these ingredients come together in our digital cauldron, a delightful AR experience is brewed! The 3D duck majestically appears, twirling and spinning in all its glory. Every magician has more than one trick up their sleeve, and so will we! Stay tuned!🎩🔮

If you've followed the steps to the letter, the enchantments inside your **`<body>`** tag should now look like this. If they don't, fear not! Even the most seasoned magic-makers sometimes stumble. Take a moment to retrace your steps, realign your magic symbols, and let's try the spell within the **`<body>`** realm again!

```html
  <a-scene vr-mode-ui="enabled: false;" loading-screen="enabled: false;" renderer="logarithmicDepthBuffer: true;"
    arjs="trackingMethod: best; sourceType: webcam; debugUIEnabled: false;" id="scene" embedded gesture-detector>
    <a-assets>
      <a-asset-item id="animated-asset" src="demo.gltf"></a-asset-item>
    </a-assets>

    <a-marker id="animated-marker" type="pattern" preset="custom" url="marker.patt" raycaster="objects: .clickable"
      emitevents="true" cursor="fuse: false; rayOrigin: mouse;" id="markerA">
      <a-entity id="bowser-model" scale="0.4 0.4 0.4" animation-mixer="loop: repeat" gltf-model="#animated-asset"
        class="clickable" gesture-handler></a-entity>
    </a-marker>

    <a-entity camera></a-entity>
  </a-scene>

```

### 3. Unleashing Multiple AR Entities (optional)

Alright, conjuring one 3D duck is cool, but you know what's cooler? Conjuring multiple 3D entities! Each entity will be linked to a different marker, leading to an entirely new model. It's like having multiple magic tricks up your sleeve!

```html
  <a-scene embedded arjs>
    <a-assets>
      <a-asset-item id="duck-model" src="Duck.gltf"></a-asset-item>
      <a-asset-item id="another-model" src="AnotherModel.gltf"></a-asset-item>
    </a-assets>
    <a-marker preset="hiro">
      <a-entity id="duck" gltf-model="#duck-model" scale="0.3 0.3 0.3"
        animation="property: rotation; to: 0 360 0; loop: true; dur: 10000; startEvents: spin">
      </a-entity>
    </a-marker>
    <a-marker preset="kanji">
      <a-entity id="another-entity" gltf-model="#another-model" scale="0.3 0.3 0.3"
        animation="property: rotation; to: 0 360 0; loop: true; dur: 10000; startEvents: spin">
      </a-entity>
    </a-marker>
    <a-entity camera>
      <a-cursor></a-cursor>
      <a-text value="Please point your camera at the Hiro or Kanji marker." align="center" position="0 -0.5 -1.5"
        color="red" visible="true"></a-text>
    </a-entity>
  </a-scene>

```

## What Did We Learn?

We've now built a basic AR application with multiple 3D models, and we didn't even need goofy glasses! Not only do we know how to set up an AR scene, but we can also add multiple 3D models to the scene and make them come alive. We've mastered the basics and we're ready to create our own digital universe. Remember, in the world of AR, the only limit is your imagination. Keep coding and keep exploring!

![https://cloud-4vl3zrzew-hack-club-bot.vercel.app/0image__5_.gif](https://cloud-4vl3zrzew-hack-club-bot.vercel.app/0image__5_.gif)

This guide outlines how to create a virtual reality scene using A-Frame, a web framework for building VR experiences. It discusses a component-based architecture to manage complexity and improve reusability.


Mastering the Matrix: Crafting Your Own Web-based AR App


In this Jam, you will make your own AI Game in 40 lines of code using Wizard Orpheus! [Wizard Orpheus](https://github.com/hackclub/wizard-orpheus) is a JavaScript library that makes it easy peasy to build AI apps in JavaScript with minimal prior knowledge!

You will get to come up with your own story, game variables, and fun mechanics. The Jam concept & library was made by [Zach Latta](https://hackclub.slack.com/team/U0266FRGP) (founder of Hack Club) and the slides / document were produced by [Thomas](https://hackclub.slack.com/team/U041FQB8VK2).

**Outline:**
1. **Fork and Run Replit**
2. **Add ability for users to send a message**
3. **Add ability for bot to respond**
4. **Create a variable to keep score**
5. **Update the background with variables** 
6. **Customize prompt to make your own game**

## Fork & Run Replit 
Visit [hack.club/wow-starter](https://hack.club/wow-starter
) and tap Fork & Run. You'll need to create a Replit account for this to work. 

![Wizard Orpheus Fork & Run Gif](https://cloud-rfnb1efui-hack-club-bot.vercel.app/0wizard-orpheus-fork-and-run.gif)
## Add ability for users to send a message
Currently when the user taps enter... 
![user tapping enter](https://cloud-wd3hweveh-hack-club-bot.vercel.app/0noenter.gif)

It does not send the message! Let's change that

Let's go into our script.js file. 

In that file, beneath our prompt (on the first line), let's add this section of code

```
myGame.createUserAction({
  name: 'message',
  parameters: ['Message from user to game'],
  howBotShouldHandle: 'Respond to the user'
})

document.getElementById('input').addEventListener('keyup', function(e) {
  if (e.code == 'Enter') { // if the user presses enter
    let userInput = document.getElementById('input').value
    myGame.message(userInput)

    document.getElementById('conversation').innerHTML += '<p>' + userInput + '</p>'

    document.getElementById('input').value = ''
  }
})
```

This code is giving the user the ability to send a message when they tap Enter. It also clears out the input afterwards so that the input is ready for the next message. 

![new code segment shown working](https://cloud-prej9qe5y-hack-club-bot.vercel.app/0newcodesegment.gif)

## Add ability for bot to respond
We're able to send a message, but we're not currently getting a response. 

With the segment of code below, we're going to give the game bot the ability to respond to our message and place it onto the screen

```
myGame.botAction('respond', 'Send a text response to the user', { message: 'What you want to say to the user' }, data => {
  // Add the bot's response to the conversation
  document.getElementById('conversation').innerHTML += '<p>' + data.message + '</p>'
})
```

Now we're able to get a response to our messages!

![getting response](https://cloud-ajjskyyoq-hack-club-bot.vercel.app/0getmeout.gif)

## Create a variable to keep score
To add more complexity to our game, we can add variables. Variables can be anything from the mood of the character you're talking with to the darkness of the room you're in. 

In this example below, let's implement a score into the game (although feel free to implement whatever variable you'd like)

```
myGame.variable('score', 'Current score. Changes (positive and negatively) as the user does things.', 0)

myGame.botAction('respond', 'Send a text response to the user', { message: 'What you want to say to the user' }, data => {
document.getElementById('conversation').innerHTML += '<p>' + data.message + '</p>'

document.getElementById('score').innerHTML = data.currentVariables.score.value
})
```

Keep in mind that you're *adding to the bot action* instead of creating a whole new bot action.

![Change my score](https://cloud-3so5m9g4f-hack-club-bot.vercel.app/0changemyscore.gif)


## Update the background with variables
You can also change the styles of the game using variables.

For example, you can change the background using variables. 

```
myGame.variable('scaredLevel', 'How scared the user is. This changes quickly. From 0 (not scared) to 50 (very scared).', 0)

myGame.botAction('respond', 'Send a text response to the user', { message: 'What you want to say to the user' }, data => {

  document.body.style.backgroundColor = `rgba(0, 0, 0, ${data.currentVariables.scaredLevel.value / 50})`

})
```

![Darken screen](https://cloud-detca5vdf-hack-club-bot.vercel.app/0darkerscreen.gif)

## Customize prompt to make your own game

Now you can change the prompt on your first line

```
var myGame = new WizardOrpheus('', `
You are an employee at the Capybara Cafe, a place rumored to use capybaras in its beverages. While the public face of the cafe is that of a charming spot offering coffee and tea, there are secrets about the ingredients used that must be kept from prying eyes, especially investigators who might disguise themselves as customers to unearth the truth.
`)
```

After you change the prompt in your game logic (script.js), you can change the content of the UI by going to your index.html file, and altering the paragraph text on line 12.

```
  <p>You are a private investigator working to uncover secrets of the Capybara Cafe. Figure out the secret and win the
    game.</p>
```

Please come up with your own game! A great example is Zach's rug merchant game where you have to convince a rug merchant to sell you a rug for only $100 when the merchant wants $200.

I was able to get the merchant to give it to me for free in a single message. Try to beat my high score (maybe that means them giving you money + the rug or maybe even giving you more rugs for free). 

Here's the link to Zach's game: [Zach's rug merchant game](https://hack.af/qv9xy)

Please share your game on the Hack Club Slack when you finish it! 


In this Jam, you will make your own AI Game in 40 lines of code using Wizard Orpheus! Wizard Orpheus is a JavaScript library that makes it easy peasy to build AI apps in JavaScript with minimal prior knowledge!
