haas/spring2026/unix/projects/fwg0.md
... ...
@@ -0,0 +1,194 @@
1
+# CSCS1730 UNIX/Linux Fundamentals
2
+
3
+# PROJECT: FUN WITH GAMES (fwg0)
4
+
5
+## OBJECTIVE
6
+
7
+Obtain the latest stable release source code, or latest repository code,
8
+of the `Vircon32` Fantasy Console, along with its `DevTools`, and modify
9
+the provided code to display a sprite, move it around the screen, and
10
+detect screen bounds.
11
+
12
+## TASK
13
+
14
+Obtain and install on your development system the latest stable release,
15
+or latest version of the repository code, of the `Vircon32` Fantasy
16
+Console, along with its `DevTools` (C compiler).
17
+
18
+NOTE: Do **not** add the source code or binary code to `Vircon32` or
19
+`DevTools` to your repository! Process these outside of your repository.
20
+Once installed, your files specifically related to your modified code
21
+SHOULD be added to your repository.
22
+
23
+There is a `README` file in the base directory of the Vircon32
24
+`ComputerSoftware` directory that includes build instructions.
25
+
26
+Verify that it works, by testing the grabit code in its initial state by
27
+ensuring the `DevTools` work when called (`compile`, `assemble`, and
28
+`packrom`), and of course running it in the `Vircon32` emulator.
29
+
30
+Then, modify the program according to the following criteria:
31
+
32
+## PROGRAM
33
+
34
+You are to write a Vircon32 C program that does the following:
35
+
36
+ * displays some "sprite" of your choosing on the screen
37
+ * moves based on the control of the first gamepad (left, right, up, down)
38
+ * screen bounds detection and handling (barrier or wrap-around)
39
+
40
+NOTE: the first gamepad by default is mapped to the keyboard
41
+
42
+While this isn't a "programming" course, it is one where we solve
43
+problems and learn to utilize available information. It is expected you
44
+make use of the Vircon32 API documentation along with asking questions on
45
+the DISCORD.
46
+
47
+## URLs
48
+
49
+The main Vircon32 site can be found [here](https://www.vircon32.com/), be
50
+sure to note the link to the Vircon32 API.
51
+
52
+The code can be found on the [Vircon32 ComputerSoftware GitHub
53
+repository](https://github.com/vircon32/ComputerSoftware/)
54
+
55
+I would recommend against checking out the tutorials: too many have
56
+gotten into trouble being influenced by the code, running into issues
57
+trying to conform to project specifications.
58
+
59
+## CARTRIDGE BUILD PROCESS
60
+
61
+You will want to create your own bash build script that will facilitate
62
+the build process from the steps laid out. You should be able to run your
63
+script and, all components being in order, produce a viable V32 file that
64
+can be played in the emulator.
65
+
66
+It should assume that the Vircon32 DevTools are present in your PATH.
67
+
68
+NOTE that with certain modifications, you'll first need to modify the XML
69
+file as appropriate before building.
70
+
71
+### COMPILE
72
+
73
+First step is to compile the C code, which can be done with the following
74
+command from the Vircon32 developer tools C compiler (`compile`):
75
+
76
+```
77
+yoursystem:~/src/SEMESTER/unix/fwg0$ compile fwg0.c -o fwg0.asm
78
+```
79
+
80
+This compiles, or translates, the C code into Vircon32 assembly language
81
+code, which will then need to be assembled to machine code:
82
+
83
+### ASSEMBLE
84
+
85
+Once you've compiled your code successfully, you can use the Vircon32
86
+`assemble` DevTool to assemble the assembly:
87
+
88
+```
89
+yoursystem:~/src/SEMESTER/unix/fwg0$ assemble fwg0.asm -o fwg0.vbin
90
+```
91
+
92
+### IMAGE CONVERSTION
93
+
94
+Any PNG images you'd like to use need to be converted to Vircon32 texture
95
+format via the `png2vircon` tool:
96
+
97
+```
98
+yoursystem:~/src/SEMESTER/unix/fwg0$ png2vircon background.png -o background.vtex
99
+yoursystem:~/src/SEMESTER/unix/fwg0$ png2vircon sprites.png -o sprites.vtex
100
+```
101
+
102
+Note that you'll also want to ensure the XML file has been updated to
103
+reference these textures:
104
+
105
+```
106
+ <binary path="fwg0.vbin" />
107
+ <textures>
108
+ <texture path="background.vtex" />
109
+ <texture path="sprites.vtex" />
110
+ </textures>
111
+```
112
+
113
+### AUDIO CONVERSION
114
+
115
+Should you have any WAV files you'd like to use need to be converted to
116
+the Vircon3 sound format via the `wav2vircon` tool:
117
+
118
+```
119
+yoursystem:~/src/SEMESTER/unix/fwg0$ wav2vircon backgroundmusic.wav -o backgroundmusic.vsnd
120
+yoursystem:~/src/SEMESTER/unix/fwg0$ wav2vircon soundfx.wav -o soundfx.vsnd
121
+```
122
+
123
+Note that you'll also want to ensure the XML file has been updated to
124
+reference these sounds:
125
+
126
+```
127
+ <sounds>
128
+ <sound path="backgroundmusic.vsnd" />
129
+ <sound path="soundfx.vsnd" />
130
+ </sounds>
131
+```
132
+
133
+### PACKING THE ROM
134
+
135
+Once all the components have been built, you can pack them together into
136
+a Vircon32 cartridge for use in the emulator via the `packrom` tool:
137
+
138
+```
139
+yoursystem:~/src/SEMESTER/unix/fwg0$ packrom fwg0.xml
140
+```
141
+
142
+## SUBMISSION
143
+
144
+To be successful in this project, the following criteria (or their
145
+equivalent) must be met:
146
+
147
+ * Project must be submit on time, by the deadline.
148
+ * Late submissions will lose 33% credit per day, with the submission window closing on the 3rd day following the deadline.
149
+ * Executed programs must display in a manner similar to provided output
150
+ * output formatted, where applicable, must match that of project requirements
151
+ * Processing must be correct based on input given and output requested
152
+ * Output, if applicable, must be correct based on values input
153
+ * Code must be nicely and consistently indented
154
+ * Code must be consistently written, to strive for readability from having a consistent style throughout
155
+ * Code must be commented
156
+ * Any "to be implemented" comments **MUST** be removed
157
+ * these "to be implemented" comments, if still present at evaluation time, will result in points being deducted.
158
+ * Sufficient comments explaining the point of provided logic **MUST** be present
159
+ * No global variables (without instructor approval), no goto statements, no calling of main()!
160
+ * Track/version the source code in your private semester repository
161
+ * Submit a copy of your source code to me using the **submit** tool by the deadline.
162
+
163
+### SUBMIT TOOL USAGE
164
+
165
+Let's say you have completed work on the project, and are ready to
166
+submit, you would do the following:
167
+
168
+```
169
+lab46:~/src/SEMESTER/unix/fwg0$ make submit
170
+```
171
+
172
+You should get some sort of confirmation indicating successful submission
173
+if all went according to plan. If not, check for typos and or locational
174
+mismatches.
175
+
176
+### RUBRIC
177
+
178
+I'll be evaluating the project based on the following criteria:
179
+
180
+```
181
+260:260:final tally of results (260/260)
182
+*:fwg0:code modified to meet project specifications [52/52]
183
+*:fwg0:screenshot or video posted to class DISCORD of game running [52/52]
184
+*:fwg0:source file, XML file, build script, and cartridge submit [52/52]
185
+*:fwg0:code compiles, cartridge builds with no warning or error [52/52]
186
+*:fwg0:committed project related changes to private semester repo [52/52]
187
+```
188
+
189
+Additionally:
190
+
191
+ * Solutions not abiding by spirit of project will be subject to a 50% overall deduction
192
+ * Solutions not utilizing descriptive why and how comments will be subject to a 25% overall deduction
193
+ * Solutions not utilizing indentation to promote scope and clarity or otherwise maintaining consistency in code style and presentation will be subject to a 25% overall deduction
194
+ * Solutions not organized and easy to read (assume a terminal at least 90 characters wide, 40 characters tall) are subject to a 25% overall deduction