Merge pull request #573 from diogotrentini/main

Update guides

Author: aduros

site/docs/guides/audio.md

@@ -375,7 +375,7 @@ Setting ADSR flags require the use of various bitwise and bitshift operations. T
 
 These functions can be used to understand how they are calculated:
 
-<!-- <MultiLanguageCode> -->
+<MultiLanguageCode>
 
 ```typescript
 function toneFrequency(freq1: i32 = 0, freq2: i32 = 0): u32 {
@@ -395,7 +395,25 @@ function toneFlags(channel: i32 = 0, mode: i32 = 0, pan: i32 = 0): u32 {
 }
 ```
 
-<!-- </MultiLanguageCode> -->
+```rust
+fn tone_frequency(freq1: u32, freq2: u32) -> u32 {
+	freq1 | (freq2 << 16)
+}
+
+fn tone_duration(attack: u32, decay: u32, sustain: u32, release: u32) -> u32 {
+	(attack << 24) | (decay << 16) | sustain | (release << 8)
+}
+
+fn tone_volume(peak: u32, volume: u32) -> u32 {
+	(peak << 8) | volume
+}
+
+fn tone_flags(channel: u32, mode: u32, pan: u32) -> u32 {
+	channel | (mode << 2) | (pan << 4)
+}
+```
+
+</MultiLanguageCode>
 
 ## Sound Tool
 

site/docs/guides/multiplayer.md

@@ -1,5 +1,7 @@
 # Multiplayer
 
+import MultiLanguageCode from '@site/src/components/MultiLanguageCode';
+
 WASM-4 supports realtime multiplayer of up to 4 players, either locally or online.
 
 Detecting [gamepad input](/docs/guides/user-input#gamepad) for Player 2 is the same as usual, but instead of
@@ -51,6 +53,8 @@ memory register.
 Reading this register is not required to implement netplay, but it can be used to implement advanced
 features such as non-shared screen multiplayer:
 
+<MultiLanguageCode>
+
 ```c
 // If netplay is active
 if (*NETPLAY & 0b100) {
@@ -60,6 +64,19 @@ if (*NETPLAY & 0b100) {
 }
 ```
 
+```rust
+unsafe {
+    // If netplay is active
+    if *NETPLAY & 0b100 != 0 {
+        let player_idx = *NETPLAY & 0b011;
+        // Render the game from player_idx's perspective
+        // ...
+    }
+}
+```
+
+</MultiLanguageCode>
+
 This is a powerful feature enabling games with hidden information, like card games, strategy games,
 and first person shooters. However, caution must be taken by developers to not introduce
 desynchronization. In other words, the netplay player index should only be used to adjust how a

site/docs/guides/sprites.md

@@ -338,20 +338,40 @@ w4 png2src --assemblyscript bunny.png
 
 Will print out the following generated source:
 
+<MultiLanguageCode>
+
 ```typescript
 const bunny_width = 16;
 const bunny_height = 16;
 const bunny_flags = 1; // BLIT_2BPP
 const bunny = memory.data<u8>([ 0xaa,0x9e,0xac,0xaa,0xaa,0x57,0xbf,0x2a,0xaa,0x57,0xbf,0x2a,0xaa,0x17,0xbf,0x2a,0xaa,0x17,0x03,0x2a,0xaa,0x57,0x54,0x2a,0xa8,0x55,0x55,0x6a,0xa9,0x55,0x05,0x0a,0xaf,0xd5,0x55,0x4a,0xa8,0x75,0x55,0x4a,0xaa,0xd5,0x57,0x2a,0xaa,0x1d,0x7c,0xaa,0xa8,0x75,0x15,0x2a,0xa8,0x45,0x15,0x2a,0xaa,0x10,0x54,0xaa,0xaa,0x85,0x52,0xaa ]);
 ```
 
+```rust
+const BUNNY_WIDTH: u32 = 16;
+const BUNNY_HEIGHT: u32 = 16;
+const BUNNY_FLAGS: u32 = 1; // BLIT_2BPP
+const BUNNY: [u8; 64] = [ 0xaa,0x9e,0xac,0xaa,0xaa,0x57,0xbf,0x2a,0xaa,0x57,0xbf,0x2a,0xaa,0x17,0xbf,0x2a,0xaa,0x17,0x03,0x2a,0xaa,0x57,0x54,0x2a,0xa8,0x55,0x55,0x6a,0xa9,0x55,0x05,0x0a,0xaf,0xd5,0x55,0x4a,0xa8,0x75,0x55,0x4a,0xaa,0xd5,0x57,0x2a,0xaa,0x1d,0x7c,0xaa,0xa8,0x75,0x15,0x2a,0xa8,0x45,0x15,0x2a,0xaa,0x10,0x54,0xaa,0xaa,0x85,0x52,0xaa ];
+```
+
+</MultiLanguageCode>
+
 Pasting that into our program, we can draw a bunny like so:
 
+<MultiLanguageCode>
+
 ```typescript
 *DRAW_COLORS = 0x2013;
 blit(bunny, 10, 10, bunny_width, bunny_height, bunny_flags);
 ```
 
+```rust
+unsafe { *DRAW_COLORS = 0x2013 }
+blit(&BUNNY, 10, 10, BUNNY_WIDTH, BUNNY_HEIGHT, BUNNY_FLAGS);
+```
+
+</MultiLanguageCode>
+
 [`DRAW_COLORS`](basic-drawing) is used here to modify the 4 colors of the original sprite. Reading
 from right to left: color 1 becomes 3, color 2 becomes 1, color 3 becomes 0 (transparent), and color
 4 becomes 2.
@@ -363,8 +383,11 @@ Use a `--template filename` for this.
 
 Templates use the `Mustache` syntax. An array called `sprites` is provided.
 
-Basic template (C):
-```
+Basic template:
+
+<MultiLanguageCode>
+
+```c
 {{#sprites}}
 // {{name}}
 #define {{name}}Width {{width}}
@@ -375,6 +398,19 @@ const uint8_t {{name}}[{{length}}] = { {{bytes}} };
 {{/sprites}}
 ```
 
+```rust
+{{#sprites}}
+// {{name}}
+const {{rustName}}_WIDTH: u32 = {{width}};
+const {{rustName}}_HEIGHT: u32 = {{height}};
+const {{rustName}}_FLAGS: u32 = {{flagsHumanReadable}};
+const {{rustName}}: [u8; {{length}}] = [ {{bytes}} ];
+
+{{/sprites}}
+```
+
+</MultiLanguageCode>
+
 Where:
 - `{{#sprites}}`, `{{/sprites}}` - Start and end of the list of sprites
 - `{{name}}` - filename (i.e. `wallTop`; string),

site/docs/guides/text.md

@@ -69,7 +69,7 @@ w4.text("Hello world!", 10, 10);
 
 The WASM-4 font contains 224 characters total.
 
-<img src="/img/charset.png" width="256" height="224" class="pixelated"/>
+<img src="/img/charset.png" width="256" height="224" className="pixelated"/>
 
 Aside from text and symbols, many slots are empty. This is because in ASCII, the text format used for the `text()` function, doesn't have any character indexed to it. Moreover, some of them *are* mapped, but as control characters.
 
@@ -80,37 +80,41 @@ It's possible to print one of these characters by escaping it's charcode.
 
 | Key         | Escape Character |
 |-------------|------------------|
-| A button    | `\x80`           |
-| B button    | `\x81`           |
+| X button    | `\x80`           |
+| Y button    | `\x81`           |
 | Left arrow  | `\x84`           |
 | Right arrow | `\x85`           |
 | Up arrow    | `\x86`           |
 | Down arrow  | `\x87`           |
 
 We could use those as instructions for our games!
 
-<!-- <MultiLanguageCode> -->
+<MultiLanguageCode>
 
 ```typescript
 // Press UP to jump!
 w4.text("Press \x86 to jump!", 10, 10);
 ```
 
-<!-- </MultiLanguageCode> -->
+```rust
+// Press UP to jump!
+text(b"Press \x86 to jump!", 10, 10);
+```
+
+</MultiLanguageCode>
 
 ## Custom Fonts
 
 Since WASM-4 doesn't have a custom font, we have to figure a way to implement our own. One way to approach this is treating a font like a tilemap, except we're indexing characters instead of numbers!
 
 The example below will print a text using the [BitScript sprite font](https://opengameart.org/content/bitscript-a-low-res-handwriting-font):
 
-<!-- <MultiLanguageCode> -->
+<MultiLanguageCode>
 
 ```typescript
 import * as w4 from "./wasm4";
 
 const fontWidth = 208;
-const fontHeight = 8;
 const fontFlags = w4.BLIT_1BPP;
 const charWidth = 8;
 const charHeight = 8;
@@ -143,6 +147,18 @@ const font = memory.data<u8>([
   0x42, 0x2c, 0x82, 0x84, 0x3a, 0x40, 0x08, 0x86,
   0x38, 0x40, 0x3a, 0x10, 0x48, 0x46, 0x30, 0x66
 ]);
+
+function drawSpace(x: i32, y: i32, column: i32, line: i32, colors: u16) {
+    store<u16>(w4.DRAW_COLORS, w4.DRAW_COLORS & 0x0F);
+    w4.rect(
+        x + (column * CHAR_WIDTH),
+        y + (line * CHAR_HEIGHT),
+        CHAR_WIDTH,
+        CHAR_HEIGHT
+    );
+    store<u16>(w4.DRAW_COLORS, colors);
+}
+
 function write(text: string, x: i32, y: i32, colors: u16): void {
     // Set draw colors...
     store<u16>(w4.DRAW_COLORS, colors);
@@ -151,32 +167,24 @@ function write(text: string, x: i32, y: i32, colors: u16): void {
     let line  : i32 = 0;
     let column: i32 = 0;
 
-    // Special characters: "\n" (newline) and " " (space).
-    const newline: i32 = 10;
-    const space  : i32 = 32;
-
     // Iterate through each character...
     for(let i = 0; i < text.length; i += 1) {
         const char: string = text.charAt(i);
         const charCode: i32 = char.charCodeAt(0);
 
         // Break into next line when encounter a "\n" (newline)...
-        if(charCode === newline) {
+        if(charCode === 10) {
             line  += 1;
             column = 0;
             continue;
         }
-        // Advance to next column when encounter a " " (space)...
-        else if(charCode === space) {
-            column += 1;
-            continue;
-        }
 
         // Character index on charset.
         let charIndex: i32 = charset.indexOf(char);
 
-        // Skip invalid characters...
+        // Skip invalid characters, spaces, etc.
         if(charIndex < 0 || charIndex >= charset.length) {
+            drawSpace(x, y, column, line, colors);
             column += 1;
             continue;
         }
@@ -204,4 +212,109 @@ export function update (): void {
 }
 ```
 
-<!-- </MultiLanguageCode> -->
+```rust
+use crate::wasm4::*;
+
+const FONT_WIDTH: u32 = 208;
+const FONT_FLAGS: u32 = BLIT_1BPP;
+const CHAR_WIDTH: u32 = 8;
+const CHAR_HEIGHT: u32 = 8;
+const CHARSET: &str = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const FONT: &'static [u8] = &[
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x08, 0x1c, 0x1c, 0x3c, 0x18, 0x3e,
+  0x1c, 0x26, 0x10, 0x2c, 0x12, 0x08, 0x24, 0x26,
+  0x1c, 0x3c, 0x1c, 0x78, 0x1c, 0x3c, 0x62, 0x42,
+  0x82, 0xc4, 0x42, 0x66, 0x08, 0x32, 0x22, 0x52,
+  0x24, 0x51, 0x22, 0x25, 0x28, 0x14, 0x14, 0x08,
+  0x24, 0x26, 0x22, 0x52, 0x22, 0xa4, 0x22, 0x52,
+  0x22, 0xa5, 0x44, 0x2a, 0x24, 0x1c, 0x14, 0x52,
+  0x20, 0x12, 0x20, 0x10, 0x20, 0x26, 0x28, 0x04,
+  0x14, 0x08, 0x2c, 0x24, 0x22, 0x52, 0x22, 0xa4,
+  0x20, 0x10, 0x22, 0x24, 0x54, 0x10, 0x24, 0x04,
+  0x14, 0x5c, 0x40, 0x22, 0x38, 0x38, 0x4e, 0x7c,
+  0x28, 0x08, 0x28, 0x10, 0x54, 0x58, 0x42, 0x14,
+  0x44, 0x78, 0x18, 0x10, 0x24, 0x28, 0x54, 0x10,
+  0x14, 0x08, 0x24, 0xa4, 0x40, 0x62, 0x40, 0x20,
+  0x44, 0x48, 0x10, 0x08, 0x34, 0x30, 0x54, 0x48,
+  0x44, 0x20, 0x54, 0x48, 0x04, 0x20, 0x44, 0x28,
+  0x2c, 0x28, 0x08, 0x10, 0x3c, 0xa4, 0x42, 0xa4,
+  0x44, 0xa0, 0x44, 0xc9, 0x10, 0x48, 0x24, 0x52,
+  0x44, 0x4a, 0x44, 0xa0, 0x3a, 0x48, 0x44, 0xa0,
+  0x44, 0x10, 0x28, 0xa8, 0x48, 0x38, 0x42, 0x5b,
+  0x3c, 0x58, 0x38, 0x40, 0x38, 0x46, 0x68, 0x34,
+  0x42, 0x2c, 0x82, 0x84, 0x3a, 0x40, 0x08, 0x86,
+  0x38, 0x40, 0x3a, 0x10, 0x48, 0x46, 0x30, 0x66
+];
+
+fn draw_space(x: i32, y: i32, column: u32, line: u32, colors: u16) {
+    unsafe { *DRAW_COLORS = *DRAW_COLORS & 0x0F }
+    rect(
+        x + (column * CHAR_WIDTH) as i32,
+        y + (line * CHAR_HEIGHT) as i32,
+        CHAR_WIDTH,
+        CHAR_HEIGHT
+    );
+    unsafe { *DRAW_COLORS = colors }
+}
+
+pub fn write(text: &str, x: i32, y: i32, colors: u16) {
+    // Set draw colors...
+    unsafe { *DRAW_COLORS = colors }
+
+    // Line and column counters.
+    let mut line: u32 = 0;
+    let mut column: u32 = 0;
+
+    // Iterate through each character...
+    for c in text.chars() {
+        let char_code = c as u32;
+
+        // Break into next line when encounter a "\n" (newline)...
+        if char_code == 10 {
+            line += 1;
+            column = 0;
+            continue;
+        }
+
+        // Character index on charset.
+        let char_index: u32;
+
+        match CHARSET.find(c) {
+            Some(x) => char_index = x as u32,
+
+            // Skip invalid characters, spaces, etc.
+            None => {
+                draw_space(x, y, column, line, colors);
+                column += 1;
+                continue;
+            }
+        }
+
+        // Draw character...
+        blit_sub(
+            FONT,
+            x + (column * CHAR_WIDTH) as i32,
+            y + (line * CHAR_HEIGHT) as i32,
+            CHAR_WIDTH,
+            CHAR_HEIGHT,
+            char_index * CHAR_WIDTH,
+            0,
+            FONT_WIDTH,
+            FONT_FLAGS
+        );
+
+        // Advance to next column...
+        column += 1;
+    }
+}
+
+#[no_mangle]
+fn update() {
+    custom::write("HELLO WORLD WITH\nOUR CUSTOM FONT", 4, 4, 0x30);
+}
+```
+
+</MultiLanguageCode>