docs: example for programmatic table creation (#65)

.gitignore

@@ -12,3 +12,6 @@ Cargo.lock
 
 # MSVC Windows builds of rustc generate these, which store debugging information
 *.pdb
+
+# output from example
+basic.vpx

README.md

@@ -10,6 +10,10 @@ Join [#vpxtool on "Virtual Pinball Chat" discord](https://discord.gg/eYsvyMu8) f
 
 https://docs.rs/vpin
 
+## Example code
+
+Check the [examples folder](examples/)
+
 ## Projects using vpin
 
 https:/francisdb/vpxtool

basic.ini

@@ -0,0 +1,15 @@
+[TableOverride]
+ViewCabMode = 2
+ViewCabScaleX = 1.280866
+ViewCabScaleY = 1.000000
+ViewCabScaleZ = 1.000000
+ViewCabRotation = 0.000000
+ViewCabHOfs = 0.000000
+ViewCabVOfs = -11.195301
+ViewCabWindowTop = 400.000000
+ViewCabWindowBot = 210.000000
+
+[Player]
+ScreenPlayerX = 0.000000
+ScreenPlayerY = -5.000000
+ScreenPlayerZ = 75.000000

examples/basic.vbs

@@ -0,0 +1,38 @@
+Option Explicit
+Randomize
+
+ExecuteGlobal GetTextFile("controller.vbs")
+
+Dim bFlippersEnabled
+
+Sub Table1_Init
+ debug.print "Hello, World!"
+ 'add a ball
+ bFlippersEnabled = True
+End Sub
+
+Sub Table1_KeyDown(ByVal Keycode)
+ debug.print "Down Keycode: " & Keycode
+ If keycode = LeftFlipperKey and bFlippersEnabled Then
+ LeftFlipper.RotateToEnd
+ End If
+ If keycode = RightFlipperKey and bFlippersEnabled Then
+ RightFlipper.RotateToEnd
+ End If
+ If keycode = PlungerKey then
+ Plunger.PullBack
+ End If
+End Sub
+
+Sub Table1_KeyUp(ByVal Keycode)
+ debug.print "Up Keycode: " & Keycode
+ If keycode = LeftFlipperKey and bFlippersEnabled Then
+ LeftFlipper.RotateToStart
+ End If
+ If keycode = RightFlipperKey and bFlippersEnabled Then
+ RightFlipper.RotateToStart
+ End If
+ If keycode = PlungerKey then
+ Plunger.Fire
+ End If
+End Sub

examples/create_basic_vpx_file.rs

@@ -0,0 +1,64 @@
+use std::path::Path;
+use vpin::vpx;
+use vpin::vpx::color::ColorNoAlpha;
+use vpin::vpx::gameitem::bumper::Bumper;
+use vpin::vpx::gameitem::flipper::Flipper;
+use vpin::vpx::gameitem::GameItemEnum;
+use vpin::vpx::material::Material;
+use vpin::vpx::VPX;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+ let mut vpx = VPX::default();
+
+ // playfield material
+ let mut material = Material::default();
+ material.name = "Playfield".to_string();
+ // material defaults to purple
+ material.base_color = ColorNoAlpha::from_rgb(0x966F33); // Wood
+ vpx.gamedata.materials = Some(vec![material]);
+
+ // black background (default is bluish gray)
+ vpx.gamedata.backdrop_color = ColorNoAlpha::from_rgb(0x060606); // Dark Gray
+ vpx.gamedata.playfield_material = "Playfield".to_string();
+
+ // add a plunger
+ let mut plunger = vpx::gameitem::plunger::Plunger::default();
+ plunger.name = "Plunger".to_string();
+ plunger.center.x = 898.027;
+ plunger.center.y = 2105.312;
+ vpx.add_game_item(GameItemEnum::Plunger(plunger));
+
+ // add a bumper in the center of the playfield
+ let mut bumper = Bumper::default();
+ bumper.name = "Bumper1".to_string();
+ bumper.center.x = (vpx.gamedata.left + vpx.gamedata.right) / 2.;
+ bumper.center.y = (vpx.gamedata.top + vpx.gamedata.bottom) / 2.;
+ vpx.add_game_item(GameItemEnum::Bumper(bumper));
+
+ // add 2 flippers
+ let mut flipper_left = Flipper::default();
+ flipper_left.name = "LeftFlipper".to_string();
+ flipper_left.center.x = 278.2138;
+ flipper_left.center.y = 1803.271;
+ flipper_left.start_angle = 120.5;
+ flipper_left.end_angle = 70.;
+ vpx.add_game_item(GameItemEnum::Flipper(flipper_left));
+
+ let mut flipper_right = Flipper::default();
+ flipper_right.name = "RightFlipper".to_string();
+ flipper_right.center.x = 595.869;
+ flipper_right.center.y = 1803.271;
+ flipper_right.start_angle = -120.5;
+ flipper_right.end_angle = -70.;
+ vpx.add_game_item(GameItemEnum::Flipper(flipper_right));
+
+ // add a script
+ let script = std::fs::read_to_string(Path::new("examples").join("basic.vbs"))?;
+ vpx.set_script(script);
+
+ vpx::write("basic.vpx", &vpx)?;
+
+ println!("Wrote basic.vpx.");
+ println!(r#"Try running it with "VPinballX_GL -play basic.vpx""#);
+ Ok(())
+}

src/vpx/color.rs

@@ -4,6 +4,83 @@ use serde::{Deserialize, Serialize};
 
 use super::biff::BiffWriter;
 
+#[derive(Debug, PartialEq, Clone, Copy, Dummy)]
+pub struct ColorNoAlpha {
+ r: u8,
+ g: u8,
+ b: u8,
+}
+
+/// Serialize as a string in the format "#RRGGBB".
+impl Serialize for ColorNoAlpha {
+ fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+ where
+ S: serde::Serializer,
+ {
+ let s = format!("#{:02x}{:02x}{:02x}", self.r, self.g, self.b);
+ serializer.serialize_str(&s)
+ }
+}
+
+// Deserialize from a string in the format "#RRGGBB".
+impl<'de> Deserialize<'de> for ColorNoAlpha {
+ fn deserialize<D>(deserializer: D) -> Result<ColorNoAlpha, D::Error>
+ where
+ D: serde::Deserializer<'de>,
+ {
+ let s = String::deserialize(deserializer)?;
+ if s.len() != 7 {
+ return Err(serde::de::Error::custom(
+ "Invalid color format, expected #RRGGBB",
+ ));
+ }
+ if &s[0..1] != "#" {
+ return Err(serde::de::Error::custom(
+ "Invalid color format, expected #RRGGBB",
+ ));
+ }
+ let r = u8::from_str_radix(&s[1..3], 16).map_err(serde::de::Error::custom)?;
+ let g = u8::from_str_radix(&s[3..5], 16).map_err(serde::de::Error::custom)?;
+ let b = u8::from_str_radix(&s[5..7], 16).map_err(serde::de::Error::custom)?;
+ Ok(ColorNoAlpha { r, g, b })
+ }
+}
+
+impl ColorNoAlpha {
+ pub fn from_rgb(arg: u32) -> Self {
+ let r = ((arg >> 16) & 0xff) as u8;
+ let g = ((arg >> 8) & 0xff) as u8;
+ let b = (arg & 0xff) as u8;
+ ColorNoAlpha { r, g, b }
+ }
+
+ pub fn to_rgb(&self) -> u32 {
+ let r = (self.r as u32) << 16;
+ let g = (self.g as u32) << 8;
+ let b = self.b as u32;
+ r | g | b
+ }
+
+ pub fn rgb(r: u8, g: u8, b: u8) -> Self {
+ Self { r, g, b }
+ }
+
+ pub fn biff_read(reader: &mut BiffReader<'_>) -> ColorNoAlpha {
+ let r = reader.get_u8();
+ let g = reader.get_u8();
+ let b = reader.get_u8();
+ let _ = reader.get_u8();
+ ColorNoAlpha { r, g, b }
+ }
+
+ pub fn biff_write(&self, writer: &mut BiffWriter) {
+ writer.write_u8(self.r);
+ writer.write_u8(self.g);
+ writer.write_u8(self.b);
+ writer.write_u8(0);
+ }
+}
+
 #[derive(Debug, PartialEq, Clone, Copy, Dummy)]
 pub struct Color {
  a: u8,
@@ -134,37 +211,20 @@ impl Color {
  b: 0,
  };
 
- // TODO do we want a BiffRead with a parameter?
-
- pub fn biff_read_argb(reader: &mut BiffReader<'_>) -> Color {
+ pub fn biff_read_bgr(reader: &mut BiffReader<'_>) -> Color {
  let a = reader.get_u8();
  let r = reader.get_u8();
  let g = reader.get_u8();
  let b = reader.get_u8();
  Color { a, r, g, b }
  }
 
- pub fn biff_read_bgr(reader: &mut BiffReader<'_>) -> Color {
- let a = reader.get_u8();
- let b = reader.get_u8();
- let g = reader.get_u8();
- let r = reader.get_u8();
- Color { a, r, g, b }
- }
-
- pub fn biff_write_argb(&self, writer: &mut BiffWriter) {
+ pub fn biff_write_bgr(&self, writer: &mut BiffWriter) {
  writer.write_u8(self.a);
  writer.write_u8(self.r);
  writer.write_u8(self.g);
  writer.write_u8(self.b);
  }
-
- pub fn biff_write_bgr(&self, writer: &mut BiffWriter) {
- writer.write_u8(self.a);
- writer.write_u8(self.b);
- writer.write_u8(self.g);
- writer.write_u8(self.r);
- }
 }
 
 impl std::fmt::Display for Color {

src/vpx/gamedata.rs

@@ -6,7 +6,7 @@ use super::{
  version::Version,
 };
 use crate::vpx::biff::{BiffRead, BiffWrite};
-use crate::vpx::color::{Color, ColorJson};
+use crate::vpx::color::{Color, ColorJson, ColorNoAlpha};
 use crate::vpx::json::F32WithNanInf;
 use crate::vpx::material::{Material, SaveMaterial, SavePhysicsMaterial};
 use crate::vpx::math::{dequantize_u8, quantize_u8};
@@ -172,7 +172,7 @@ pub struct GameData {
  pub glass_bottom_height: Option<f32>, // GLAB 70.5 (added in 10.8)
  pub table_height: Option<f32>, // TBLH 71 (optional in 10.8)
  pub playfield_material: String, // PLMA 72
- pub backdrop_color: u32,  // BCLR 73 (color bgr)
+ pub backdrop_color: ColorNoAlpha, // BCLR 73 (color bgr)
  pub global_difficulty: f32, // TDFT 74
  pub light_ambient: u32, // LZAM 75 (color)
  pub light0_emission: u32, // LZDI 76 (color)
@@ -341,7 +341,7 @@ pub(crate) struct GameDataJson {
  pub glass_bottom_height: Option<f32>,
  pub table_height: Option<f32>,
  pub playfield_material: String,
- pub backdrop_color: u32,
+ pub backdrop_color: ColorNoAlpha,
  pub global_difficulty: f32,
  pub light_ambient: u32,
  pub light0_emission: u32,
@@ -827,7 +827,7 @@ impl Default for GameData {
  glass_bottom_height: None, // new default 210 for both
  table_height: None, //0.0,
  playfield_material: "".to_string(),
- backdrop_color: 0x232323ff, // bgra
+ backdrop_color: ColorNoAlpha::from_rgb(0x626E8E), // Waikawa/Bluish Gray
  global_difficulty: 0.2,
  light_ambient: 0x000000ff, // TODO what is the format for all these?
  light0_emission: 0xfffff0ff, // TODO is this correct?
@@ -1125,7 +1125,7 @@ pub fn write_all_gamedata_records(gamedata: &GameData, version: &Version) -> Vec
  writer.write_tagged_f32("TBLH", table_height);
  }
  writer.write_tagged_string("PLMA", &gamedata.playfield_material);
- writer.write_tagged_u32("BCLR", gamedata.backdrop_color);
+ writer.write_tagged_with("BCLR", &gamedata.backdrop_color, ColorNoAlpha::biff_write);
  writer.write_tagged_f32("TDFT", gamedata.global_difficulty);
  writer.write_tagged_u32("LZAM", gamedata.light_ambient);
  writer.write_tagged_u32("LZDI", gamedata.light0_emission);
@@ -1373,7 +1373,7 @@ pub fn read_all_gamedata_records(input: &[u8], version: &Version) -> GameData {
  "GLAB" => gamedata.glass_bottom_height = Some(reader.get_f32()),
  "TBLH" => gamedata.table_height = Some(reader.get_f32()),
  "PLMA" => gamedata.playfield_material = reader.get_string(),
- "BCLR" => gamedata.backdrop_color = reader.get_u32(),
+ "BCLR" => gamedata.backdrop_color = ColorNoAlpha::biff_read(reader),
  "TDFT" => gamedata.global_difficulty = reader.get_f32(),
  "LZAM" => gamedata.light_ambient = reader.get_u32(),
  "LZDI" => gamedata.light0_emission = reader.get_u32(),
@@ -1593,7 +1593,7 @@ mod tests {
  glass_bottom_height: Some(123.0),
  table_height: Some(12.0),
  playfield_material: "material_pf".to_string(),
- backdrop_color: 0x333333ff,
+ backdrop_color: ColorNoAlpha::rgb(0x11, 0x22, 0x33),
  global_difficulty: 0.3,
  light_ambient: 0x11223344,
  light0_emission: 0xaabbccdd,

src/vpx/gameitem.rs

@@ -13,6 +13,7 @@ pub mod lightsequencer;
 pub mod plunger;
 pub mod primitive;
 pub mod ramp;
+pub mod ramp_image_alignment;
 pub mod reel;
 pub mod rubber;
 pub mod spinner;